Fieldmotion API Getting started

Work areas and stock categories

Replace a work-area location’s details

POST /a/Location_edit

Patch a work area without clearing omitted address, coordinates or customer fields.

When to use this endpoint

Read the current area through Location_get, then send only the fields to change. Omitted values are preserved.

These records represent work areas and map locations, not live user GPS positions or geofence definitions. Read IDs before editing; the stored user column is distinct from user-to-area membership.

Authentication and permissions

Authenticate using signed API-key fields or a logged-in CRM session. All object queries use the authenticated tenant. The handler has no additional page, role or feature check unless stated below.

Sign numeric request values as strings, including nested native arrays; only JSON-encode parameters that explicitly accept JSON text. See Getting started.

Parameters

ParameterTypeRequiredDescription
idPositive integerYesOne positive integer ID of an active tenant-local record; arrays, negative numbers and SQL-like strings are rejected.
nameStringNoTrimmed, nonempty name. No handler length limit or uniqueness check; the schema still constrains storage.
lat / lngNumber-compatible scalarNoFinite latitude between -90 and 90 and longitude between -180 and 180, inclusive. Zero is valid; nonnumeric and out-of-range values are rejected.
customer_idNonnegative integerNoCreation defaults to no customer; zero clears the link. Positive IDs must identify a non-deleted customer in this tenant. Sets customer_type to 1 for a customer, otherwise 0.
addressString or nullNoSaved when supplied; omission on creation uses the schema default. An edit preserves the existing address when omitted; null clears it.
user_idIgnoredNoDoes not change stored user_id or user-to-area assignment links.

Example request

$result = FM_api('Location_edit', ['id'=>'1042','name'=>'Depot','lat'=>'54.6','lng'=>'-5.9','address'=>'Example Road','customer_id'=>'0']);

Example response

{"ok":1}

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 not a single positive integer.
{"error":"That location does not appear to exist"}No non-deleted row matches.
{"error":"missing or invalid parameter: name"}Supplied name is not a nonempty trimmed string.
{"error":"missing or invalid parameter: lat"}Supplied latitude is invalid; longitude uses lng.
{"error":"customer does not exist"}Supplied positive customer ID has no active row.
{"error":"inventory write failed"}Update failed and rolled back.

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

Behaviour and edge cases

  • Requires a positive ID of a non-deleted work area. Supplied fields are validated like creation; omitted fields remain unchanged.
  • Even an id-only/no-op edit stamps the server datetime. changes and user assignment are not changed.
  • Tenant row changes, membership repairs and required audit writes are checked within one transaction; a failure rolls them back and returns an error. Configured events run only after commit.
  • Only non-deleted work areas are read or changed. No department or ownership restriction is applied. CRM1/CRM2 hide Area Settings with feature bit 524288, but these APIs do not enforce that UI restriction.
  • The source search found no direct caller in the mobile JavaScript app or its m/www intermediary for this endpoint.

Side effects

  • Updates the location row and server-datetime last_edited; invalidates locations cache. Does not persist user_id, changes or user-to-area links.

See it in Fieldmotion

CRM1

Open Area Settings and create or edit a map location; filter browser Network requests for this endpoint. The screen sends name, coordinates, customer_id and address.

CRM2

Open Area Settings and create or edit an area; filter browser Network requests for this endpoint. The current save payload sends address but omits customer_id.

Related endpoints