Fieldmotion API Getting started

Customers

Retrieve customer coordinates

POST /a/Customer_getLocation

Retrieve one customer’s stored coordinates and name for map and job-location flows.

When to use this endpoint

Use Customer_getLocation when a caller needs the customer’s already-stored point and should fail if either coordinate is zero.

It does not geocode or repair the record. Use Customer_geocode to resolve an address, then explicitly save approved coordinates.

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 ID.

Example request

$location = FM_api('Customer_getLocation', [
	'id' => '1042',
]);

Example response

{
  "latitude": "54.5973",
  "longitude": "-5.9301",
  "name": "Northwind Service Centre"
}

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 not positive.
{"error":"customer does not exist: 1042"}No row has that ID.
{"error":"customer does not have lat/lon coordinates set"}Either stored coordinate compares equal to string 0.

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

Behaviour and edge cases

  • Returns database values without numeric conversion, so coordinates normally appear as JSON strings.
  • A module-global customer cache can satisfy the lookup when populated during the same PHP request; otherwise the database row is read.
  • Zero in either axis is treated as missing even though a coordinate on an equator or prime-meridian axis can be legitimate.
  • There is no pagination.

See it in Fieldmotion

CRM1

The route is used indirectly by Job_getLocation for jobs belonging directly to a customer. No direct CRM1 network caller was found.

CRM2

No direct CRM2 caller was found. Customer/map components generally use mapped detail data.

Related endpoints