Fieldmotion API Getting started

Quotes: settings, costing and lookups

Change quote status and queue Workflow

POST /a/Quote_setStatus

Store a quote status and, when enabled, record its bound Workflow transition.

When to use this endpoint

Use for an explicit quote status transition. Won date is stamped atomically; this endpoint does not itself create a Job or invoice.

Authentication and permissions

Authenticates a signed API key or CRM session as its tenant user. Requires Quotes View (pageQuotes_view). Non-admin users blocked by legacy crm_access bit 32 are denied. Roleless non-admin users fail closed. Also requires Quotes Edit (pageQuotes_edit); client administrators inherit page permissions.

Uses local tenant IDs. The active quote must also satisfy the account’s customer department/account-manager visibility filters for non-admin users, including signed-key requests.

Parameters

ParameterTypeRequiredDescription
idPositive integer-compatible quote IDYesPositive local quote ID, integer-converted; an active quote is required.
statusInteger-compatible statusYes-1 Draft; 0 Quoted; 1 Won; 2 Paid; 3 Cancelled; 4 Needs Customer Approval; 5 Approved by Customer; 6 Lost; 7 Further Action Required; 8 On Hold. Other values fail.

Example request

$result = FM_api('Quote_setStatus', ['id'=>'1042','status'=>'1']);

Example response

{"ok":1}

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":"quote does not exist"}The active quote is missing (lookup failures are reported separately).
{"error":"Unable to save quote. Check the saved state before retrying."}Database, audit, transaction or commit acknowledgement failed. Refresh saved state before retrying an uncertain commit.
{"error":"permission denied"}Required Quotes permission is absent or the non-admin actor is blocked by legacy access settings.
{"error":"id and status parameters are both required"}Missing/nonpositive quote ID or missing status.

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

Behaviour and edge cases

  • Accepts only -1 Draft, 0 Quoted, 1 Won, 2 Paid, 3 Cancelled, 4 Needs Customer Approval, 5 Approved by Customer, 6 Lost, 7 Further Action Required and 8 On Hold.
  • Locks the quote before comparing its old status. Equal status returns warning=no update needed without history, won-date or Workflow work.
  • Status=1 writes the server’s current YYYY-MM-DD to won_date in the same transaction. Moving away from Won preserves that date.
  • With features2.workflow=1, records the matching active Form/status Workflow binding as a durable queued run. Status, won-date, history and the enqueue commit together; enqueue failure rolls back. Already-run/queued and unbound transitions do not create another run. Worker actions execute later.
  • Locks the active quote in a tenant transaction. Bound writes, last_edited (server-local date/time), quote history and quotes cache invalidation are checked together. Audit or primary write failure rolls back. Existing caller transactions retain a savepoint; an uncertain commit returns an error and is never replayed automatically.
  • No direct mobile app/m-service caller for this RPC was found.

Side effects

  • Updates the named data and last_edited, records quote history and requests quotes cache invalidation in the tenant transaction. No ordinary mention notice, notification or email is sent by this dedicated handler.
  • A bound Workflow can later create work or send messages; execution is asynchronous. Won date saves with status.

See it in Fieldmotion

CRM1

Quotes Status cell and Customer Quotes actions call Quote_setStatus with id/status.

CRM2

No direct browser RPC found. When Workflow is enabled, Quote_updateData/updateField delegates status changes internally to Quote_setStatus; inspect the outer mapped request. Without Workflow the mapped path differs.

Related endpoints