Fieldmotion API Getting started

Purchase orders

Read an order target summary

POST /a/PurchaseOrder_getTargetDetails

Return display strings describing the linked target and relevant customer or owner.

When to use this endpoint

Use for the explanatory label in the delivery-address dialog. This is a display summary, not a structured target record.

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_getTargetDetails', [
	'id'=>'1042',
]);

Example response

[
  "Customer - Northwind Depot",
  " Parent - Northwind Group"
]

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 purchase order 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

  • Returns display strings for permitted linked objects, retaining legacy labels and leading-space " Parent - " text. Customer/Quote/customer-Job branches may add one immediate parent; asset Jobs may add the owner.
  • Each related query enforces the corresponding object View permission and scope. Missing/inaccessible references omit their names; historical unknown-Job customer/asset placeholders can remain. No target/Warehouse gives [].
  • The order itself must exist and be visible. No pagination, recursive parent traversal or writes. These strings are presentation labels, not stable typed identifiers.

Side effects

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

See it in Fieldmotion

CRM1

In CRM1 Purchase Order details, open Find Address. The dialog calls PurchaseOrder_getTargetDetails to display its target summary.

CRM2

CRM2 Purchase Order details calls the same endpoint while building the delivery-address dialog.

Related endpoints