Fieldmotion API Getting started

Work areas and stock categories

Retrieve selected raw work areas

POST /a/Locations_getById

Fetch raw location fields for a known batch of IDs.

When to use this endpoint

Locations_list can discover the IDs. This batch endpoint reduces round trips, but does not preserve input ordering.

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
idsNative array or JSON array textYesIDs are integer-converted. Empty array returns []; malformed JSON is not safely validated.
fieldsNative array or JSON array textNoAllowed stored fields: id, name, lat, lng, changes, last_edited, address, user_id, customer_type, customer_id. Unknown fields are ignored; a supplied list with no valid selections returns an error. Omission selects all allowed fields.

Example request

$result = FM_api('Locations_getById', ['ids'=>json_encode(['1042']), 'fields'=>json_encode(['id','name'])]);

Example response

[{"id":"1042","name":"Depot"}]

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: ids"}IDs omitted.
{"error":"no fields selected"}Supplied field list contains no allowed columns.

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

Behaviour and edge cases

  • Omitted fields select all ten raw columns. Invalid fields are ignored, duplicates removed, and no valid selection returns an error; id need not be selected.
  • Missing rows are omitted. Request order is not preserved; no ordering or pagination is established. Repeated IDs do not duplicate rows.
  • Supply well-formed arrays: malformed fields/ids may cause PHP warnings rather than stable validation errors.
  • 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

  • Read-only; no object writes, audit entries or notifications are performed.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found for this endpoint. The legacy Area Settings screen uses Locations_get and Location_get.

CRM2

No direct CRM2 caller was found for this endpoint. CRM2 Area Settings uses Locations_get and legacy Location_add/Location_edit writes.

Related endpoints