Query the mapped Users table

When to use this endpoint

Use for CRM2 Users lists, export-selection and restricted list pickers. This shares DataProcessClass with other mapped table APIs, but has User-specific filters and post-processing.

Send a native fields list. The helper that recognizes picker fields can parse JSON text, but the actual table/enrichment pipeline still expects an array.

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.

Users View is required, with strict role checks. The bounded CRM2 listPicker exception permits only its declared picker fields; roleCheck never bypasses authorization.

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

Example request

$result = FM_api('Users_getDataTable', [
	'fields'=>['id', 'name', 'active', 'departments'],
	'draw'=>'1',
	'start'=>'0',
	'length'=>'10',
]);

Example response

{
  "data": [
    {
      "id": "1042",
      "name": "Alex Morgan",
      "active": "1",
      "departments": [
        "18"
      ]
    }
  ],
  "draw": 1,
  "recordsTotal": "1",
  "recordsFiltered": "1"
}

Errors and unusual responses

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

Behaviour and edge cases

• Strict Users View applies unless the constrained CRM2 listPicker exception matches. roleCheck is ignored and cannot disable authorization.
• Excludes meta.is_tmp whose extracted text equals 1; a present false/zero differs from the stricter SQL-null exclusion in Users_list. No parent/active filter is automatically added, and users is not a soft-delete table in this helper.
• Requested ordinary columns preserve database types/JSON text. departments is decoded to an array, falling back to CSV splitting; blank storage can therefore return [""], not []. Nested mapped references such as role use their declared map layout; hidden fields are not automatically removed.
• password, gcmId and widgetPassword are rejected before querying. Raw meta is returned as sanitized JSON text without trusted login tokens; pay_type is blank without financial authority. Cost/rate/hours fields require financial authority.
• area is a list of type-7 Location ID strings; skill is a list of integer Skill IDs without multipliers. allocatedToJob contains incomplete, non-deleted direct-user Jobs whose scheduled start is at least now minus their own duration, ordered by start; it includes future Jobs without a right-hand time bound. Entries are {id,meetingTime,hours}, with local datetime and numeric hours.
• With GPS account feature bit 16, all returned rows receive gpsCreateDate/gpsLatitude/gpsLongitude from latest GPS, or blank strings, even when those fields were not requested.
• Skill name search uses EXISTS so multiple matching skills do not duplicate users. Ordering appends user ID ASC. recordsTotal counts visible non-temporary users before request filters; recordsFiltered counts the filtered rows before page slicing.
• All main queries and counts apply TeamAccess user scope. The legacy department-based fallback applies only to otherwise unrestricted roles; CSV and JSON department membership both work.
• Native controls are validated before mapped SQL construction: flat field/ID lists, bounded paging, asc/desc directions and allowlisted advanced-search conditions. Raw advanceSearch.where SQL is rejected.

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

No direct production caller was found in CRM1; its Users screen uses the positional Users_getDT contract.

CRM2

Open CRM2 Users or an assignee picker and filter Users_getDataTable. The export-selection pass requests fields=[id], isTable=0, limit=0; picker calls use the constrained listPicker marker.

Related endpoints

• Users_getDT — Compare CRM1’s positional table format.
• Users_list — Read the basic selectable user list and its explicit scope predicate.
• Users_getExportData — Follow the two-phase legacy export contract.