Fieldmotion API Getting started

Purchase orders

Find delivery-address candidates

POST /a/PurchaseOrder_findAddresses

Build labelled address choices from the order’s current address, company and linked target.

When to use this endpoint

Use before PurchaseOrder_setDeliveryAddress. Results are candidate [label,address] pairs, not normalized address records or distance/geocode results.

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

Example response

[
  [
    "Current",
    "Northwind Depot\n12 Harbour Road"
  ],
  [
    "Company Address",
    "Fieldmotion Offices\nExample Road"
  ]
]

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: id"}id converts below 1.
{"error": "purchase order does not exist"}No matching order.
{"error": "permission denied"}The required page/action or legacy visibility setting denies access.

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 ordered [label,address] pairs: saved current address, company-address when configured, then candidates derived from the linked target. No sorting, deduplication, geocoding or pagination.
  • Related object names/addresses require their own View permission and visibility. Missing/inaccessible customers are omitted; a missing/blank Location address retains the Unknown placeholder.
  • Contract, Customer, Quote, customer/asset Job and Location target branches retain the established labels. Customer text joins name, populated address lines and country; an immediate parent may add another candidate. Asset ownership/location can repeat candidates.
  • Ordinary dirty Contract membership is derived from visible Jobs, using old many-to-many links only when no current Contract Jobs exist. Programme explicit membership remains authoritative. This reader no longer repairs Contract storage or relationship rows.
  • Historical related lookups retain their existing record-lifecycle rules; address candidates are not an active-record catalogue. No deletion lifecycle or schema change is part of this reader.

Side effects

  • Read-only: does not rebuild Contract caches, update edit markers, change relationships, choose/save an address or send messages.

See it in Fieldmotion

CRM1

In CRM1 Purchase Order details, choose Find Address. Watch PurchaseOrder_getTargetDetails and PurchaseOrder_findAddresses, then PurchaseOrder_setDeliveryAddress when confirming a choice.

CRM2

CRM2 Purchase Order details uses the same target-details and address-candidate calls in its address dialog.

Related endpoints