Set a customer town · Fieldmotion API

When to use this endpoint

Use Customer_setTown for a focused town correction on a known customer address.

Use the address retrieval endpoint first when the caller needs the customer’s assembled current or historical address.

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

Parameter	Type	Required	Description
`id`	Integer string	Yes	Customer to update; it must convert to a positive integer.
`val`	String	Yes	New town, trimmed before comparison and storage. A present blank value clears it; the setter imposes no length limit.

Example request

$result = FM_api('Customer_setTown', [
	'id' => '1088',
	'val' => 'Carrickfergus',
]);

Example response

{
  "ok": 1
}

An unchanged trimmed town returns {"ok":1,"msg":"no change needed"}.

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":"missing or invalid parameter: id"}`	`id` is absent or invalid.
`{"error":"missing or invalid parameter: val"}`	`val` was omitted.
`{"error":"customer does not exist"}`	No matching customer row exists.

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

Behaviour and edge cases

Address-history errors are ignored. The handler calls Address_set first but discards its response, so the town can be stored and success returned after the history step rejected the assembled address.

The lookup has no active/deleted filter.
The final setter performs no town format or length validation.
Helper side effects and the final field write are not one transaction.
This is a single-record mutation; it provides no list filtering or pagination.

Side effects

Address_set can update address history, clear cached customer details on linked non-deleted jobs and invoices, and mark this customer and descendants as edited.
The final write updates town, last_edited, and edited_uuid, invalidates the customer cache, logs the edit, and fires Customer_edit.

See it in Fieldmotion

CRM1

Open the legacy customer edit popup, change Town, and filter Network requests for Customer_setTown.

CRM2

No direct production CRM2 caller was found. CRM2 saves customer addresses through its layout-driven update contract.

Related endpoints

Customer_getAddress returns assembled current or historical address data.
Customer_get retrieves the current customer row.