Fieldmotion API Getting started

Customers

Set both customer coordinates

POST /a/Customer_setLatLng

Replace both customer coordinates and synchronize address history and dependent address snapshots.

When to use this endpoint

Use Customer_setLatLng when a map or geocoder has produced a complete latitude/longitude pair for an existing customer.

Use the individual latitude or longitude setter only when intentionally preserving the other stored coordinate.

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 valueNoNew latitude after floatval conversion. Omitted, blank, and nonnumeric values become 0.
lngNumeric-like valueNoNew longitude after floatval conversion. Omitted, blank, and nonnumeric values become 0.

Example request

$result = FM_api('Customer_setLatLng', [
	'id' => '1088',
	'lat' => '54.5973',
	'lng' => '-5.9301',
]);

Example response

{
  "ok": 1
}

If both converted coordinates loosely equal their stored values, the endpoint 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":"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.
  • Both coordinates are compared with PHP loose equality before writing.
  • 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 and longitude, 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 Customers map and bulk geolocation workflows call Customer_setLatLng after resolving coordinates.

CRM2

CRM2 uses the same endpoint from its customer map and bulk geolocation workflows. Filter Network requests by Customer_setLatLng while updating mapped customers.

Related endpoints