Fieldmotion API Getting started

Customers

Set a customer lead/account state

POST /a/Customer_setLeadAcc

Set the legacy lead/account workflow state stored on one customer.

When to use this endpoint

Use Customer_setLeadAcc only when reproducing the legacy Customers-table lead/account control.

The value partly represents derived job state. Job recounts can replace manually stored values, so it is not a durable free-form classification field.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesCustomer to update; it must convert to a positive integer.
valInteger-like valueYesPositive state value after intval. UI/helper meanings are 1 lead with no jobs, 2 lead with open jobs, 3 account with closed but no open jobs, 4 account with open and closed jobs, and 5 lost. The handler itself accepts any positive integer.

Example request

$result = FM_api('Customer_setLeadAcc', [
	'id' => '1088',
	'val' => '5',
]);

Example response

{
  "ok": 1
}

A loosely equal raw request value returns {"ok":1,"msg":"no change needed"}.

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 is absent or invalid.
{"error":"missing or invalid parameter: val"}val is absent, zero, negative, or otherwise converts below one.
{"error":"customer does not exist"}No customer row matches the ID.

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

Behaviour and edge cases

  • The customer lookup does not filter inactive or soft-deleted records.
  • Although the UI uses values 1–5, the handler has no upper bound and no reference-table validation.
  • The no-change comparison uses the stored value and raw request value with PHP loose equality.
  • This is a single-record mutation; it provides no list filtering or pagination.

Side effects

  • The write changes lead_acc, updates last_edited, and sets edited_uuid to Customer_setLeadAcc. It does not explicitly invalidate the customer cache or fire Customer_edit.
  • A customer audit event is written. No customer_changes row is added.

See it in Fieldmotion

CRM1

The inline lead/account control on the legacy Customers table reaches Customer_setLeadAcc through the dynamic customer setter route.

CRM2

CRM2 exposes equivalent customer data through its layout editor, but no direct production call to this focused endpoint was found.

Related endpoints