Fieldmotion API Getting started

Purchase orders

Read configurable line export rows

POST /a/PurchaseOrders_getExportLineItemsData

Return one selected-field export object per saved line of the selected orders.

When to use this endpoint

Use after the CRM2 Purchase Orders table has supplied header IDs. This endpoint accepts header IDs rather than line IDs and returns JSON for client-side CSV construction.

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

ParameterTypeRequiredDescription
_idsNonempty JSON array stringYesLocal Purchase Order header IDs. Native arrays, [] and sentinel "1" are not this selection contract. IDs must be positive integers and are validated before querying.
fieldsNonempty JSON array stringYesRequested export fields: po_id, po_num, reference, name, cdate, date_approved, date_sent, delivery_date, target_id, target_type, stock_type, amt, total_net, total_tax, nominal_code, status, ro_id, meta_date_order_fully_received. Positions become f0,f1,…; po_id, stock_id and stock_text are additionally returned regardless of the selected list.

Example request

$rows = FM_api('PurchaseOrders_getExportLineItemsData', [
	'_ids'=>json_encode(['1042']),
	'fields'=>json_encode(['po_id','stock_type','amt','nominal_code','status']),
]);

Example response

[
  {
    "po_id": "1042",
    "stock_id": "0",
    "stock_text": "Packing materials",
    "f0": "1042",
    "f1": "Packing materials",
    "f2": "2.5000",
    "f3": "EXP-LOCAL",
    "f4": "Open"
  }
]

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: _ids"}Selection is absent.
{"error": "_ids should be a JSON array of numbers"}Selection fails the nonempty JSON-array check.
{"error": "fields should be an array of requested field names"}Projection is missing, empty or invalid.
{"error": "unknown field name: unsupported"}A field is outside the allowlist; supplier_id and metaStatus are not supported despite dormant conversion branches.
{"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

  • Returns a bare array sorted by header ID, line sort_num and line ID. Multiple rows can share po_id; no line ID is returned. Orders with no lines contribute no row. No paging/counts/cap or initial ID-discovery mode is supported.
  • 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.
  • Selected headers must be active and visible. Supplier and stock display values require their related View and active/scoped record checks.
  • stock_type is an export-description column: catalogue rows resolve the stock name, miscellaneous rows use stock_text. A missing catalogue lookup can remain false/blank. The raw stock_id and stock_text are retained alongside the selected f columns.
  • status becomes Open, Part Received, Complete, Over-received or Cancelled. target_type labels include Warehouse; target_id stays numeric. name is the authorized supplier name. Line totals exclude carriage; no carriage row is added.
  • meta_date_order_fully_received maps missing/JSON null to blank. Repeated requested columns receive identical transformations. Unknown and custom-table fields return errors before querying.

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. CRM1 uses PurchaseOrders_exportLineItems.

CRM2

In CRM2 Purchase Orders, choose the line-item export map. The page first fetches all matching active header IDs through PurchaseOrders_getDataTable, then widgetExportCRM2 posts batches to this route.

Related endpoints