Fieldmotion API Getting started

Customers

Set a customer latitude

POST /a/Customer_setLat

Change one customer latitude while synchronizing address history and dependent address snapshots.

When to use this endpoint

Use Customer_setLat when a geocoding or map workflow needs to correct latitude without changing longitude.

Use Customer_setLatLng when both coordinates are available so the address-history workflow runs once.

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.
latNumeric-like valueYesNew latitude after floatval conversion. Blank and nonnumeric strings become 0; no geographic range check is applied.

Example request

$result = FM_api('Customer_setLat', [
	'id' => '1088',
	'lat' => '54.5973',
]);

Example response

{
  "ok": 1
}

A loosely equal stored latitude 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 omitted, zero, or otherwise invalid.
{"error":"missing or invalid parameter: lat"}lat is omitted.
{"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 has no active/deleted filter.
  • The comparison uses PHP loose equality, so equivalent string and numeric representations take the no-change path.
  • Address-history helper calls and the coordinate update are not one transaction, and helper responses are not returned to the caller.
  • This is a single-record mutation; it provides no list filtering or pagination.

Side effects

  • The primary write changes latitude, updates last_edited and edited_uuid, and invalidates the customer cache.
  • The address-history helper snapshots the assembled old and new address. Its Address_set path can clear cached customer details on linked non-deleted jobs and invoices and mark the customer hierarchy as edited.
  • After synchronization, linked non-deleted jobs whose customer_details is null are populated with current address data. Invoice snapshots cleared by Address_set are not repopulated here and remain null until another invoice refresh path runs. The handler also logs the edit and fires Customer_edit.

See it in Fieldmotion

CRM1

The legacy customer coordinate popup can call Customer_setLat when latitude is edited independently. Filter Network requests by the exact function name.

CRM2

No direct production CRM2 caller was found; CRM2 map and geocoding workflows use Customer_setLatLng for both coordinates.

Related endpoints