Fieldmotion API Getting started

Customers

Set a customer city

POST /a/Customer_setCity

Change the city on one customer while attempting to preserve address history and refresh dependent customer details.

When to use this endpoint

Use Customer_setCity for a focused city correction on a known customer address.

Use Customer_getAddress first when the current or historical full address matters; this endpoint accepts only one component.

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.
valStringYesNew city after trimming. Blank and "0" are rejected, so this endpoint cannot clear the city. No length limit is enforced here.

Example request

$result = FM_api('Customer_setCity', [
	'id' => '1088',
	'val' => 'Belfast',
]);

Example response

{
  "ok": 1
}

An unchanged trimmed city 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"}The value is omitted, blank after trimming, or exactly "0".
{"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

  • The customer lookup has no active/deleted filter.
  • The address helper can validate the complete assembled address, not only the city supplied here. The final city write is not limited to the helper’s rules.
  • The helper and final update are not one transaction, so dependent cache resets can occur before a later database failure.
  • This is a single-record mutation; it provides no list filtering or pagination.

Side effects

  • Before the field update, Address_set can insert or merge 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 city, last_edited, and edited_uuid, invalidates the customer cache, writes a customer audit entry, and fires Customer_edit.

See it in Fieldmotion

CRM1

Open the legacy customer edit popup, change City, and filter Network requests for Customer_setCity. The field saves immediately.

CRM2

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

Related endpoints