Purchase orders
Read an order reference
/a/PurchaseOrder_getReference
Fetch only the saved reference string for one Purchase Order.
When to use this endpoint
Use when an existing order ID must be translated to its saved reference. This is not the displayed numeric po_num.
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
| Parameter | Type | Required | Description |
|---|---|---|---|
po_id | Integer-compatible | Yes | Positive local Purchase Order ID/digit string; not the displayed po_num. Missing, malformed or inaccessible IDs fail. |
Example request
$result = FM_api('PurchaseOrder_getReference', [
'po_id'=>'1042',
]);Example response
"PO-NORTH-318"Errors and unusual responses
| Response | Condition |
|---|---|
{"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"} | po_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 the saved scalar reference, not an object. A blank saved reference remains blank; missing/inaccessible orders return a stable error.
- po_id is required and must be a positive integer. No reference generation, pagination or sorting occurs.
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 Purchase Order details obtains reference as part of PurchaseOrder_get.
CRM2
No direct CRM2 caller was found. The mapped Purchase Order detail read supplies reference.
Related endpoints
PurchaseOrder_get— Read the current raw header.PurchaseOrder_setReference— Change the free-text reference.PurchaseOrder_setNum— Change the displayed number.