Fieldmotion API Getting started

Purchase orders

List linked Goods Received IDs

POST /a/PurchaseOrder_getGRNs

Read the receipt-header IDs linked to a Purchase Order.

When to use this endpoint

Use when an order screen must link to its Goods Received Notes. Fetch receipt details through the Goods Received APIs separately.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Session requests use dispatcher CSRF protection when configured.

Requires explicit View on Purchase Order or Purchase Orders. Writes also require the matching Edit permission; clearing invoice details requires Delete. A non-administrator blocked by the legacy Purchase Orders visibility flag (crm_access bit 256) is denied. API keys use their owner’s permissions.

The primary order is checked against the current tenant and Purchase Order record scope. Configured TeamAccess follows permitted linked Contracts, Customers, Jobs, Quotes and Departments; the legacy department filter follows direct Customer/Quote/customer-Job links. An inaccessible or missing order returns purchase order does not exist.

Parameters

ParameterTypeRequiredDescription
idInteger-compatibleYesPositive local Purchase Order ID/digit string; not the displayed po_num. Missing, malformed or inaccessible IDs fail.

Example request

$result = FM_api('PurchaseOrder_getGRNs', [
	'id'=>'1042',
]);

Example response

[
  {
    "id": "901"
  }
]

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": "no PO id supplied"}id absent/null.
{"error": "permission denied"}The required page/action or legacy visibility setting denies access.
{"error": "purchase order does not exist"}The primary order is missing or outside the caller’s permitted scope.

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

Behaviour and edge cases

  • Requires an existing visible primary order. Receipt identifiers are exposed only with Goods Received View; otherwise the result is [].
  • Returns {id:...} objects with raw database IDs, ordered by receipt ID. No pagination/counts. It does not fetch receipt bodies or change receipt state.

Side effects

  • Reads data without changing Purchase Orders, stock, edit markers, history or notifications.

See it in Fieldmotion

CRM1

In CRM1 Purchase Order details, the receipt-link section calls PurchaseOrder_getGRNs.

CRM2

No direct CRM2 caller was found; its layout reader can request grnIDs and returns a flat list instead of {id:...} rows.

Related endpoints