Work areas and stock categories
Select work-area location fields
/a/Locations_list
Select raw work-area fields for user assignments, scheduling or customer-area selectors.
When to use this endpoint
Locations_getById is the follow-up batch read when you already have IDs. Here, the user filter is useful for work-area assignments, not ownership.
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
| Parameter | Type | Required | Description |
|---|---|---|---|
fields | Native array or JSON array text | Yes | Allowed stored fields: id, name, lat, lng, address, user_id, customer_id, last_edited. Unknown fields are ignored; a supplied list with no valid selections returns an error. Omission selects all allowed fields. |
user_id | Integer-compatible | No | If supplied, uses manymany relation type 7: from_id=user, to_id=location. Zero is still a filter; omission lists all locations. |
Example request
$result = FM_api('Locations_list', ['fields'=>json_encode(['id','name']), 'user_id'=>'42']);Example response
[{"id":"1042","name":"Depot"}]Errors and unusual responses
| Response | Condition |
|---|---|
{"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: fields"} | No valid requested field remains; checked before login. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- At least one valid field is required; id is not automatically added. Unlike batch reads, a field list is mandatory.
- No pagination, ordering or name search is implemented. All matching records are returned, including areas associated with inactive users.
- The user filter reads assignment links rather than
locations.user_id. With no matching links, returns [] immediately. - 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/wwwintermediary for this endpoint.
Side effects
- Read-only; no object writes, audit entries or notifications are performed.
See it in Fieldmotion
CRM1
Users → edit user → Work Areas loads all id/name options, then calls Locations_list with user_id and fields=[id] to select existing assignments. Scheduler and customer editors use it too.
CRM2
Form Edit’s work-area filter selector requests id/name through Locations_list; filter that name in Network.
Related endpoints
Location_getRequestedDetailsuses the mapped CRM2 field names.