Read the legacy Purchase Order grid

When to use this endpoint

Use for the existing CRM1 DataTables grid. For named mapped fields use PurchaseOrders_getDataTable; their filters, counts and response positions differ.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Session requests use dispatcher CSRF protection when configured. API keys use their owner’s identity.

Purchase Order View is required on the singular or plural page. Records must be active and inside the configured TeamAccess or legacy Department Based Filter boundary; administrators are exempt from record restrictions. API-key requests use their owner’s identity. Related display names require the corresponding page View and record visibility.

Parameters

Parameter	Type	Required	Description
`start / length`	Integer-compatible	Yes	Row offset and page size. Values are integer-converted without bounds or a special all-rows sentinel.
`order[0].column / order[0].dir`	Native nested order array	Yes	Sort indices: 0 ID, 1 po_num, 2 form, 3 reference, 4 supplier name, 5 creation, 6 approval, 7 raw net, 8 raw tax, 9 raw gross, 10 status. Index 11 sorts target type; unknown indices sort ID. Use asc or desc; malformed directions are rejected.
`draw`	Integer-compatible	No	Echoed as integer; default 0.
`search[value]`	Native nested search text	No	Trimmed/lowercased substring search over ID, po_num, reference and supplier name. LIKE wildcards are not escaped as literals.
`cancelled / overdue`	Integer-compatible flags	No	Default cancelled=0 excludes status 4; any nonzero includes it rather than selecting it exclusively. overdue nonzero requires status<2 and delivery_date before server now, including earlier today.
`dateFrom / dateTo`	Date strings	No	Apply together to creation time: >=dateFrom and <=dateTo plus 23:59:59. No strict calendar parsing here.
`order_id / po_num / form_id`	Integer-compatible	No	Nonzero values add exact header ID, displayed number or form filters.
`reference`	Text	No	Substring condition when the key is present, including blank. The text is escaped before the substring query; LIKE wildcards retain their meaning.
`received_status`	Integer-compatible	No	If present and integer-converts >=0, adds exact received status. Still combines with the cancelled exclusion; requesting status 4 requires cancelled=1.
`customer_id`	Integer-compatible	No	Nonzero ID follows direct Customer, Quote customer or ordinary customer-Job link; combines with department filtering.

Example request

$result = FM_api('PurchaseOrders_getDT', [
	'start'=>'0','length'=>'10','draw'=>'1',
	'order'=>[['column'=>'1','dir'=>'asc']],
	'search'=>['value'=>'PO-318'],
]);

Example response

{
  "draw": 1,
  "recordsTotal": "12",
  "recordsFiltered": "1",
  "data": [
    [
      "1042",
      "318",
      "5",
      "PO-318",
      "Example supplier",
      "2026-11-05 09:00:00",
      null,
      "35.00",
      "7.00",
      null,
      "0",
      "42",
      "0",
      "0",
      [
        "",
        ""
      ],
      null,
      null,
      [
        0,
        []
      ]
    ]
  ]
}

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": "missing or invalid parameter: start"}`	A required paging key is absent; length has its own equivalent error.
`{"error": "missing or invalid parameter: [order][0][dir]"}`	The first order item lacks direction; column has its own equivalent error.
`{"error":"permission denied"}`	The required page permission is missing. Hidden/deleted records are omitted from collections; explicit parent readers reject an inaccessible parent.

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

Behaviour and edge cases

Each data row has 18 positions: 0 header ID, 1 po_num, 2 form ID, 3 reference, 4 supplier name, 5 creation time, 6 approval time, 7 raw net, 8 raw tax, 9 sent time, 10 received status, 11 supplier ID, 12 target type, 13 target ID, 14 [customer ID,name], 15 delivery date, 16 stored invoice_received, 17 [returned flag,return rows].
Raw net/tax include carriage. invoice_received remains its stored value, potentially JSON text. Return rows contain grec_id, po_id, gret_id and gret_date for active Goods Returned headers; the flag indicates presence, not returned quantity.
The legacy Department Based Filter follows direct Customer links, Quote customers and ordinary customer-Job links; restricted users cannot discover unlinked or other unsupported targets. Configured TeamAccess uses the same boundary as the singular header readers.
Data and both counts exclude deleted or inaccessible headers. recordsTotal includes Cancelled orders within that boundary; recordsFiltered applies status/search/date filters before paging. Supplier/customer display lookups require related View and visibility.
Rows sort by the selected field without a stable ID tie-breaker. Query failure produces empty data rather than a distinct query-error object. No extra fields projection or sparse response is supported.

Side effects

Reads tenant data without modifying orders, lines, stock, approval, history or notifications.

See it in Fieldmotion

CRM1

In CRM1 Purchase Orders, load the grid, choose dates or search/filter and inspect PurchaseOrders_getDT. The page sends native DataTables search/order structures.

CRM2

No direct CRM2 literal caller was found in the searched client source. CRM2 uses PurchaseOrders_getDataTable.

Related endpoints

PurchaseOrders_getDataTable — Select mapped active header rows.
PurchaseOrders_exportData — Read selected configurable header export rows.
PurchaseOrder_get — Read one checked raw header.