Fieldmotion API Getting started

Purchase orders

Resolve an order document filename

POST /a/PurchaseOrder_getFilename

Expand the configured po-filename pattern for a Purchase Order.

When to use this endpoint

Use to obtain the filename value expected by document consumers. This endpoint returns JSON metadata, not a PDF, file stream, Content-Disposition header or share token.

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

Example response

{
  "value": "purchase-order"
}

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": "invalid parameter: id"}id converts below 1.
{"error": "not logged in"}No current tenant parent is available.
{"error": "purchase order does not exist"}Pattern configured but no non-deleted 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

  • Requires a positive visible existing order before reading the pattern or returning the purchase-order fallback. Missing/inaccessible orders fail even when no pattern is configured.
  • Reads the latest po-filename value, supporting plain text or {value:...}. Exact case-sensitive tokens ID,PO_NUM,DATE,SUPPLIER use saved order/current permitted supplier data. Related names require their own View permission and scope.
  • Target-specific tokens remain JOB_ID,JOB_REF,CUSTOMER_NAME,CONTRACT_NAME,QUOTE_ID,QUOTE_NUMBER,DEPARTMENT_NAME,LOCATION_NAME in double braces. Unknown/unresolved tokens remain literal. DATE is saved cdate.
  • Returns {value:...} JSON only. Does not append an extension, sanitize configured text, generate a report or issue a share token; file consumers retain their own naming rules.

Side effects

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

See it in Fieldmotion

CRM1

No direct CRM1 caller was found. CRM1 Settings → General exposes po-filename with the original ID/number/date/supplier tokens.

CRM2

No direct CRM2 caller was found. CRM2 Settings → General maintains po-filename; report/filename consumers may apply their own filename rules.

Related endpoints