Fieldmotion API Getting started

Contracts

Build the contract stock table

POST /a/Contracts_getStockDT

Build CRM1’s active-contract stock table with legacy linked-job IDs and completed direct-job stock-use payloads.

When to use this endpoint

Use Contracts_getStockDT only for CRM1’s Contract Stock screen and its positional rows.

Use normal job/stock APIs when you need one consistent relationship model or a named response schema.

Authentication and permissions

The route requires tenant routing established by a valid API signature or CRM session. It checks tenant context rather than calling the shared login guard.

Parameters

ParameterTypeRequiredDescription
lengthInteger stringYesPage size after integer conversion. Blank/zero is not explicitly rejected.
startInteger stringNoZero-based offset; defaults to 0.
drawInteger stringOperationally yesInteger-converted and echoed. The handler reads it without an existence check, so omission can emit a PHP notice and normally yields 0.
search[value]StringNoWhen nonblank, searches contract name by substring.
order[0][column]Integer stringNo0 orders by name, 1 by legacy arithmetic expiry_date-cdate, and other supplied indexes by ID. Omission leaves database order unspecified.
order[0][dir]StringWith order columnExact asc selects ascending; every other value selects descending.

Example request

$table = FM_api('Contracts_getStockDT', [
	'draw' => '4',
	'start' => '0',
	'length' => '25',
	'order' => [['column' => '0', 'dir' => 'asc']],
	'search' => ['value' => 'north'],
]);

Example response

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

Row positions are contract ID, name, native legacy-linked job-ID array, creation date, expiry date, nested decoded stock-use arrays, then three empty placeholders.

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":"not logged in"}Tenant routing is unavailable.
{"error":"missing or invalid parameter: length"}length is absent.

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 all/completed-status option.
  • Each qualifying direct job contributes one decoded stock_used value when it is nonblank and not the exact string []. Invalid JSON becomes a null element rather than an error.
  • The column-1 expression subtracts database date/datetime values numerically; it is not a portable duration sort and treats null/legacy dates according to the database’s coercion rules.

See it in Fieldmotion

CRM1

Open Contract Stock. Search, sorting, and paging call Contracts_getStockDT.

CRM2

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

Related endpoints