Fieldmotion API Getting started

User accounts and profiles

Read users for route scheduling

POST /a/Users_getSchedulerInfo

Combine active users, skills, work shifts, start coordinates and vehicle costs.

When to use this endpoint

Use for CRM2 Scheduler setup after choosing user IDs. This supplies input data; it does not calculate a route, test Job conflicts or reserve workers.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Session requests use the dispatcher’s CSRF protection when configured.

Configured TeamAccess row scope is applied in the queries. Ordinary collection requests do not need artificial record IDs. Explicit IDs still pass dispatcher record authorization; unavailable IDs can be rejected there rather than silently omitted.

Login is required. No additional page permission is imposed by this handler.

Financial fields require client administrator, explicit Users Edit, or the legacy Salaries permission (general permission bit value 8). Unauthorised list projections omit those fields; explicitly requested table/export financial fields return a permission error.

Parameters

ParameterTypeRequiredDescription
idsNative or JSON positive ID listNoOptional selection; omitted means all visible active non-temporary users, [] means none. Malformed values return an error.

Example request

$result = FM_api('Users_getSchedulerInfo', [
	'ids'=>json_encode(['1042']),
]);

Example response

[
  {
    "id": 1042,
    "name": "Alex Morgan",
    "active": "1",
    "vehicle_id": "vehicle-uuid",
    "cost_per_hour": 20,
    "work_location_id": "18",
    "skills": [
      {
        "id": 3,
        "multiplier": 0.5
      }
    ],
    "work_hours": {
      "version": 2,
      "shifts": []
    },
    "shifts": [],
    "loc": {
      "lat": 54.35,
      "lon": -6.65
    },
    "cost_per_km": 0,
    "departments": {
      "18": 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":"invalid parameter: example"}A supplied native control is malformed; the response names that control. Lists must be flat, and numeric IDs must be positive integers unless the parameter explicitly permits zero.

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

Behaviour and edge cases

  • Calls Users_list with active=1 and a fixed projection, retaining row scope and the temporary-user exclusion. No scheduler feature gate is added.
  • Start location is a nonzero user work_location_id, else work-start-location. The selected Location must exist and not be deleted; an invalid nonzero user location does not fall back a second time. loc contains numeric lat/lon or false.
  • Digit-only vehicle_id values look up vehicles.id; legacy nonnumeric values look up vehicles.uuid. A match yields numeric cost_per_km from cost_per_distance, otherwise zero. The legacy name is retained without distance-unit conversion or a new vehicle deletion filter.
  • cost_per_hour and cost_per_km are numbers when financially authorised, otherwise omitted. Skills use the Users_list shape. CSV/JSON departments normalize to an ID-keyed map with value 1.
  • When HR enhancements are disabled, work_hours is null and shifts is []; otherwise custom schedules or account fallback are normalized and included. No pagination/ordering.
  • Omitted ids selects all visible eligible users; [] returns []; malformed lists return an error. Nested Users_list errors propagate.

Side effects

  • Reads data without changing business records, edit markers, activity history or notifications. Shared setting reads can populate their normal settings cache.

See it in Fieldmotion

CRM1

CRM1’s Scheduler uses Users_list with a similar field set; no direct caller of this combined route was found.

CRM2

Open the Scheduler widget in CRM2. widgetScheduler calls Users_getSchedulerInfo with JSON.stringify of selected user IDs.

Related endpoints