Read user availability around a Job time

When to use this endpoint

Use for the assign-user-by-location dialog. The caller computes distances and sorting; the API does not rank users by proximity or reserve their time.

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.

Parameters

Parameter	Type	Required	Description
`latitude / longitude`	Numeric strings	Yes	Required finite numeric coordinates, latitude -90..90 and longitude -180..180, including zero. Used by the caller for distance ranking, not by this query.
`time`	Account-local datetime string or supported Unix seconds	Yes	Required tenant-local time string or accepted Unix timestamp; must parse to a positive timestamp no later than year 2200.
`duration`	Integer seconds	No	Positive integer seconds, default 1, maximum 31536000. Availability covers the complete requested interval.

Example request

$result = FM_api('Users_listAvailability', [
	'latitude'=>'54.35',
	'longitude'=>'-6.65',
	'time'=>'2026-11-03 10:00:00',
	'duration'=>'3600',
]);

Example response

[
  {
    "id": "1042",
    "name": "Alex Morgan",
    "email": "alex@example.test",
    "availability": {
      "user_id": 1042,
      "available": 1,
      "event": null,
      "events": []
    }
  }
]

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: latitude"}`	latitude absent/null.
`{"error": "missing or invalid parameter: longitude"}`	longitude absent/null.
`{"error": "missing or invalid parameter: time"}`	time is absent, unparseable, nonpositive or later than year 2200.
`{"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

Selects visible current-parent active users with SQL-null is_tmp, ordered by ID. No pagination, skill filter or distance ranking is applied.
Effective availability combines approved non-deleted company, role, department and user events intersecting the complete requested interval, plus normalized work shifts. More specific events win per segment (user, department, role, company), with newest cdate/last_edited/id breaking ties. Every segment must be available; a short available override cannot clear another blocked segment.
availability contains integer user_id, available 0/1, a winning/blocking event or null, and the applicable events list. Outside-shift blockers can be synthetic events; stored events include normalized IDs/flags, epoch bounds, status/name/notes and decoded meta. This is not a complete event-history listing.
With HR enhancements disabled, availability is available=1 with event=null and events=[], rather than a disabled-feature error. The endpoint still supplies surrounding Jobs.
prev is the latest visible non-deleted direct-user Job at or before time; next is the earliest strictly after time. user_type must be 0. Completion/end-time conflicts are not checked. Equal times use Job ID as a tiebreaker. Objects retain raw id,meeting_time_e,customer_id,customer_type,hours and may add customer name and numeric latitude/longitude.
customer_type selects customer or asset enrichment. Asset Jobs resolve the current customer location when configured, otherwise the owner. The resolved visible non-deleted customer supplies name/coordinates. Missing or inaccessible references leave location enrichment absent.
Department event targets normalize both CSV and JSON memberships. Time, finite coordinate ranges and a positive bounded duration are validated before availability calculations. Surrounding Jobs do not prove a conflict-free assignment.

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

Open the CRM1 assign-user-by-location dialog. customerSelectByLocation sends coordinates and the selected meeting time, then computes distances in JavaScript.

CRM2

CRM2’s location-based assignee dialog sends an account-formatted time and duration in seconds to Users_listAvailability, then sorts the candidates client-side.

Related endpoints

Users_getSchedulerInfo — Read combined scheduling inputs.
User_getWorkShifts — Inspect custom versus fallback work hours.