Fieldmotion API Getting started

User accounts and profiles

Read legacy User export batches

POST /a/Users_getExportData

Select export IDs, then fetch requested positional export columns.

When to use this endpoint

Use the two-phase workflow used by CRM1 and CRM2 User CSV export. The endpoint returns data; CSV construction and column headers are client-side.

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.

Explicit Users View and Export Table Data on the main page are required in both phases.

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
_ids1, JSON list or native listYesExactly 1 selects IDs using filters; otherwise provide a flat positive ID list. [] returns an empty data batch. Malformed values return invalid parameter: _ids.
fieldsJSON list or native string listData phaseData-phase columns in f0/f1 order, preserving duplicates. Names: id,name,email,worker_id,parent,colour,departments,cost_per_hour,price_per_hour,hours_per_week,vehicle_id,work_location_id,phone_mobile,phone_landline,date_of_birth,address,next_of_kin,active,date_created,last_login,app_permissions,crm_permissions,role_id; custom: reads custom values. Financial columns require financial authority.
search / name / email / date_createdStringsID phase onlyContains filters; search covers name/email/textual ID. Name is lowercased; email uses legacy double escaping. The data phase does not reapply them.
activeInteger stringID phase onlyBlank/omitted/-1 leaves status unfiltered; 0 or 1 selects that status.
userIDInteger stringID phase onlyNonnegative integer; zero disables the filter.
roleIDList / departmentList / activeListNative or JSON listsID phase onlyValidated nonnegative role/department IDs or active flags 0/1. Empty lists leave that filter unset. Departments match numeric boundaries in CSV/JSON storage.
idsNative or JSON positive ID listOptional ID phaseNarrows ID selection to the selected users. Explicit [] selects no users; omitted leaves selection to other filters and scope.

Example request

$result = FM_api('Users_getExportData', [
	'_ids'=>json_encode(['1042']),
	'fields'=>json_encode(['name', 'worker_id', 'custom:badge']),
]);

Example response

[
  {
    "id": "1042",
    "f0": "Alex Morgan",
    "f1": "ENG-1042",
    "f2": "A"
  }
]

Only id and requested positional aliases are exposed; raw user metadata stays internal.

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: _ids"}_ids absent/null.
{"error":"invalid parameter: _ids"}Data-phase IDs are malformed, nested or nonpositive.
{"error":"invalid parameter: fields"}fields is absent or not a flat string list.
{"error": "unknown field name: example"}An ordinary export field is not mapped; the name is appended.
{"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

  • ID phase returns {ids:[integer IDs]} ordered by ID, intersecting selected ids and row scope. Temporary/inactive rows remain eligible unless filtered.
  • Data phase rechecks scope and returns rows ordered by user ID, without reapplying the earlier search filters. Missing rows are omitted. id and the requested fN aliases are returned; raw meta is never returned.
  • Ordinary fields retain database types and stored JSON/CSV text. worker_id is extracted from metadata. Every repeated alias is normalized consistently.
  • crm_permissions and app_permissions become the established newline-separated CRM1 permission descriptions, including every duplicate requested alias.
  • custom: reads saved custom_values; absent values return an explicit null fN. Other colon-qualified names and unknown ordinary fields return an error.
  • No batch-size cap or pagination is added. Clients manage batches and must not assume selection and data fetch form a snapshot.

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

In CRM1 Users, click Export CSV. widgetExport first calls Users_getExportData with _ids=1 and current filters, then requests field batches using JSON _ids.

CRM2

CRM2 Users uses the same legacy export function after a mapped-table ID selection; widget parameters alone are not proof that the backend consumes every selection control.

Related endpoints