Fieldmotion API Getting started

Contracts

Build the contract orders table

POST /a/Contracts_getOrdersDT

Build CRM1’s combined contract requisition/purchase-order table as two independently paged legacy queries concatenated into positional rows.

When to use this endpoint

Use Contracts_getOrdersDT only for CRM1’s Contract Orders screen. Its paging is not a conventional combined result set.

New consumers should use the dedicated order APIs and contract details instead of depending on this legacy table.

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.

The CRM1 Contract Orders tab is hidden unless tenant feature bit 262144 is enabled, but the endpoint itself does not enforce that setting.

Parameters

ParameterTypeRequiredDescription
lengthInteger stringYesPer-source page size. Each of the requisition and purchase queries receives this limit, so the final response can contain up to twice this number.
startInteger stringNoOffset independently applied to both source tables; defaults to 0.
drawInteger stringNoDataTables counter, integer-converted and echoed; defaults to 0.
order[0][column]Integer stringNo0 contract name, 1 order ID, 2 reference, 3 supplier, 4 creation date, 5 approval date, 6 delivery date, or 7 status. Other/absent values use creation date. Some choices are invalid for one or both source queries.
order[0][dir]StringNoExact desc selects descending; every other value selects ascending.
search[value]StringNoIntended to search contract name, purchase reference, or supplier name. Any nonblank value currently builds invalid SQL because the source queries do not join suppliers and the requisition query has no reference column.

Example request

$table = FM_api('Contracts_getOrdersDT', [
	'draw' => '3',
	'start' => '0',
	'length' => '10',
	'order' => [['column' => '4', 'dir' => 'desc']],
	'search' => ['value' => ''],
]);

Example response

{
  "draw": 3,
  "recordsTotal": "7",
  "recordsFiltered": "7",
  "data": [
    ["North Region Service Contract", "Requisition Order", "42", "Replacement parts", "2026-03-01 10:00:00", null, "2026-03-08", "Approved", [], "720"],
    ["North Region Service Contract", "Purchase Order", "91", "PO-91", "2026-03-02 11:00:00", "2026-03-03", "2026-03-09", "Part Received", [{"id":"17"}], "720"]
  ]
}

Row positions are contract name, literal order type, order ID, requisition description/purchase reference, creation date, approval date, delivery date, status label, goods-received-note ID objects (purchase only), and target contract ID.

Requisition status indexes map to Open, Approved, Processed, Received, Cancelled. Purchase indexes map to Open, Part Received, Complete, Over-received, Cancelled.

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; blank is accepted and converted to zero.
Database-query failure or empty dataA nonblank search, supplier sort, or a source-incompatible sort references a column/table unavailable to that query.

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 orders with target_type=1 and a non-deleted contract qualify. The row queries do not exclude soft-deleted orders, but both counts do, so returned rows and counts can disagree.
  • Requisitions and purchases are each sorted, offset, and limited separately, then requisitions are placed before purchases. The combined array is neither globally sorted nor globally paged and can contain 2 × length rows.
  • recordsTotal and recordsFiltered add the two non-deleted source counts. Goods-received-note lookups do not apply a deleted filter.
  • An out-of-range stored status has no defined label and can emit a PHP notice/null value.

See it in Fieldmotion

CRM1

Open a contract’s Orders tab with the purchase-order feature enabled. The legacy table calls Contracts_getOrdersDT.

CRM2

CRM2’s contract Orders page uses contract-detail and newer order APIs; a production-source search found no direct call to this endpoint.

Related endpoints