Fieldmotion API Getting started

Work areas and stock categories

Create a work-area location

POST /a/Location_add

Create a named work area with validated coordinates, an optional address and customer link.

When to use this endpoint

Create a work area in one call, including its address. Use Location_edit to patch it later.

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
nameStringYesTrimmed, nonempty name. No handler length limit or uniqueness check; the schema still constrains storage.
lat / lngNumber-compatible scalarYesFinite 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.

Example request

$result = FM_api('Location_add', ['name'=>'Depot', 'lat'=>'54.6', 'lng'=>'-5.9', 'customer_id'=>'0']);

Example response

{"ok":1,"id":1042}

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 parameter: name"}Name omitted.
{"error":"missing or invalid parameter: name"}Name is not a string or trims to empty.
{"error":"missing or invalid parameter: lat"}Latitude missing, nonnumeric, nonfinite or out of bounds; longitude uses the corresponding lng error.
{"error":"customer does not exist"}Positive customer ID has no active tenant row.
{"error":"inventory write failed"}Insert failed; no success ID is returned.

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

Behaviour and edge cases

  • Saves supplied address. id and user_id are ignored; creation does not assign users.
  • Sets changes to literal JSON text [] and last_edited to the current server datetime. No geocoding or name uniqueness check is performed.
  • 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

  • Inserts one location and invalidates the locations cache. No user-to-area link, address history, customer update or event is created.

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