Fieldmotion API Getting started

Work areas and stock categories

Import or patch work-area rows

POST /a/Locations_import

Apply a positional field mapping to a batch of location CSV rows.

When to use this endpoint

Locations_getExportData provides raw IDs for update imports. Validate the mapping and input rows before import, then re-read results; inserts are not safe to replay.

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
mapJSON array textNoDefaults []. Entry index determines source column; each entry’s to is id/name/address/customer_id/lat/lng. from, idx, filter and options are ignored.
rowsJSON array textNoDefaults []. Each row is a positional array matching map indexes; send valid JSON arrays.

Example request

$result = FM_api('Locations_import', ['map'=>json_encode([['to'=>'name'],['to'=>'lat'],['to'=>'lng']]), 'rows'=>json_encode([['Depot','54.6','-5.9']])]);

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: map/rows"}Decoded map or rows is not an array.
{"error":"unknown import field"}Destination is not allowed.
{"error":"missing import column: 0"}A row lacks a mapped positional column; error contains the actual index.
{"error":"That location does not appear to exist"}A positive mapped ID has no active row.
{"error":"missing parameter: name"}An inserted row omits name.
{"error":"inventory write failed"}Any persistence failure rolls back the entire batch.

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

Behaviour and edge cases

  • Positive mapped IDs must exist and be non-deleted; zero/missing ID inserts. Names are required for inserts, but omitted update fields are preserved. No name matching or duplicate detection.
  • Destinations are limited to id, name, address, customer_id, lat and lng. Unknown destinations, malformed JSON/rows or missing source columns reject the batch; from/idx/filter/options are ignored.
  • Uses the same supplied-field validation as Location_add/edit, including valid zero coordinates and active-customer checks. Missing import coordinates use schema defaults; supplied customer_id recalculates customer_type.
  • Prepares and validates every row before any write, then executes checked writes in one tenant transaction. Empty rows default to [] and return ok without writes. No saved-ID list is returned.
  • 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 or updates each mapped location, advances last_edited and invalidates locations cache per row. No audit history, deletion event, user assignment or geocoding occurs.

See it in Fieldmotion

CRM1

Area Settings → Import configures name/latitude/longitude/address/customer mappings and sends Locations_import through widgetImport. The extra v=2 flag is ignored.

CRM2

No direct CRM2 caller found; current Area Settings exposes JSON-backed export and legacy single-row edits, not this import handler.

Related endpoints