Purchase orders
Query the mapped order line table
POST
/a/PurchaseOrderEntries_getDataTable
Page mapped line objects using shared layout filters and field projection.
When to use this endpoint
Use when the table consumer needs named mapped fields. Supply poID to select a parent; a legacy po_id control is not a mapped predicate.
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 |
|---|---|---|---|
fields | Native array of mapped names | Yes | Native list, not a JSON-encoded string. id is always selected; unknown names and client-only calculations are omitted. Picker objects are rebuilt from backing fields; backing fields not explicitly requested can be removed from each response row. |
start / length / draw | Integer-compatible strings | No | Table mode defaults start=0, length=10, draw=0. start is a row offset; draw is echoed as integer. Negative or malformed paging values are rejected; no maximum page size is imposed. |
isTable / limit | Integer-compatible flags | No | Default table mode. isTable=0 removes table paging/counts; only a positive limit then caps rows, while limit=0 means unlimited. start/length do not limit unpaged exports. |
orderBy / orderDesc | Mapped field / direction | No | Provide both for named sorting in table mode; use asc or desc. Without them, order[0].column selects a field position after subtracting 1 (clamped at 0); exact order[0].dir=desc descends. No ID tie-breaker is added. |
searchValue / searchField | Text / native field list or name | No | Nonblank searchValue searches mapped fields and configured related display names. Default searchField is All. SQL LIKE wildcards retain their meaning. |
Mapped field filters | Scalars, native arrays or pickers | No | Filters combine with AND. Text scalars use case-insensitive substring matching unless the map declares exact matching; lists use IN. Numeric scalars integer-convert, including decimal fields; list values follow numeric type conversion. Pickers match their ID/type components. |
referenceDate / dateFrom / dateTo | Mapped date field / relative day offsets | No | A valid referenceDate activates date filtering when both day offsets are supplied. Ranges include start-day midnight through end-day 23:59:59; the account timezone chooses today (fallback UTC). Unpaged results sort by the reference field ascending. |
offsetFrom / offsetTo | Native {hour,minute} objects | No | Additional date-time boundary offsets: hour is negated, minute is added. Not applied to date-only fields. These are legacy client controls, not general timezone identifiers. |
timeRangeFrom / timeRangeTo | Integer hours | No | With a valid referenceDate, timeRangeFrom activates an inclusive hour filter; omitted upper hour defaults 23 and reversed bounds swap. timeRangeTo alone does not activate it. Hour conversion uses the account timezone, fallback Europe/London. |
groupBy / advanceSearch | Native arrays | Legacy controls | Mapped grouping and advanced-search rules feed the shared SQL helper. Grouping does not make the count queries grouped counts. Use structured mapped conditions; do not submit raw SQL controls. |
poID / roID | Integer-compatible parent filter | Recommended | Both map to the parent po_id. No parent selector is required; omission queries lines only under active visible parents. po_id is not a mapped filter; use poID. |
Example request
$result = FM_api('PurchaseOrderEntries_getDataTable', [
'fields'=>['id','poID','stock','amt'],
'poID'=>'1042','start'=>'0','length'=>'10','draw'=>'1',
'orderBy'=>'sortNumber','orderDesc'=>'asc',
]);Example response
{
"data": [
{
"id": "2081",
"poID": "1042",
"stock": {
"id": "0",
"type": "2",
"text": "Packing materials"
},
"amt": "2.5000"
}
],
"draw": 1,
"recordsTotal": "12",
"recordsFiltered": "1"
}Errors and unusual responses
| Response | Condition |
|---|---|
{"error": "missing or invalid parameter: fields"} | fields is absent. |
{"error": "error in database query"} | The shared SELECT fails. |
{"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
- Selectable fields: id, roID/poID, stockType/stockID/stockText/stock, amt, costNet, totalNet/totalTax, cDate/lastEdited, nominalCode/nominal_code, taxTypeID/taxType, sortNumber. totalGross is a client calculation, not a stored returned amount.
- Uses checked mapped controls and an active/scoped parent predicate. nominalCode remains the stored code here; it is not normalized to a local nominal-account ID.
- recordsTotal counts lines under active visible parents; recordsFiltered adds requested filters before pagination. Hidden/deleted parents contribute no lines.
- Unpaged mode returns only {data:[...]}, with no draw/counts. Scalar numeric filters can truncate fractions even though returned/stored quantities retain them. No server row formulas are evaluated.
- Native field, grouping, sort and structured advanced-search controls are checked; raw where expressions and malformed values are rejected before SQL. Pagination values are nonnegative integers; no maximum size is imposed.
Side effects
- Reads tenant data without modifying orders, lines, stock, approval, history or notifications.
See it in Fieldmotion
CRM1
No direct CRM1 literal caller was found in the searched client source. Its legacy line editor uses PurchaseOrderEntries_get instead.
CRM2
No direct CRM2 literal caller was found in the searched client source. The Purchase Order layout reads through PurchaseOrderEntry_getLayoutDetails.
Related endpoints
PurchaseOrderEntries_get— Read the legacy ordered/received grid.PurchaseOrderEntry_getRequestedDetails— Use explicit checked mapped line detail selection.