Fieldmotion API Getting started

User clock-ins

Export clock-in data

POST /a/UserClockins_getExportData

Run the Clock-ins export’s two-phase ID discovery and batched field/job enrichment protocol.

When to use this endpoint

Use UserClockins_getExportData with CRM’s export mapper: first request filtered IDs using _ids=1, then submit JSON ID/field arrays in one or more data batches.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
_idsStringYesExact 1 selects ID-discovery mode. Otherwise it must be a nonempty JSON array; values are integer-converted before the data query.
days_from / days_to / user_id / flagged / notes / sourceDiscovery filtersNoDiscovery-only filters matching relative stored dates, positive user ID, exact flag/source, and notes substring. flagged is the flag parameter name here.
adjustedOnlyInteger-likeNoDiscovery-only exact 1 applies the same legacy adjusted predicate as UserClockins_getDataTable.
fieldsJSON array textYes for data batchesOrdered export field identifiers. Native arrays are not accepted by the implementation’s JSON decoder.
_all_idsJSON array textNoFull export ID set used by date-range totals while _ids contains only the current batch. Invalid/empty input falls back to the batch IDs.

Example request

// Phase 1
$selection = FM_api('UserClockins_getExportData', [
	'_ids' => '1',
	'days_from' => '-30',
	'days_to' => '0',
	'user_id' => '18',
]);

// Phase 2
$rows = FM_api('UserClockins_getExportData', [
	'_ids' => json_encode(array_slice($selection['ids'], 0, 100)),
	'_all_ids' => json_encode($selection['ids']),
	'fields' => json_encode(['id', 'date', 'duration', '1:job_ref', 'date_range_total_raw']),
]);

Example response

[
  {
    "clockin_cdate": "1790413212",
    "clockout_cdate": "1790442018",
    "user_id": "18",
    "f0": "481",
    "f1": "2026-09-26",
    "f2": "8h 0m",
    "f4": 55800,
    "1:job_ref": "[\"JOB-1042\",\"JOB-1047\"]"
  }
]

Discovery mode instead returns {"ids":[481,482,...]}, ordered by stored date ascending.

Ordinary requested fields are returned as f0, f1, and so on using their original fields index. Requested 1:... job fields keep that key and contain a JSON-encoded array string. The helper columns clockin_cdate, clockout_cdate, and user_id are always present in data rows.

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"}The mode/ID parameter is absent.
{"error":"_ids should be a JSON array of numbers"}Data-mode _ids does not decode to a nonempty array.
{"error":"fields should be an array of requested field names"}fields does not decode to a nonempty array.
{"error":"unknown field name: ..."}An ordinary field is outside the supported map.
{"error":"invalid job field: ..."}A 1: field is outside the supported job map.

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

Behaviour and edge cases

  • Supported ordinary fields are id, user_id, date, start/end epochs, creation epochs, geolocation/distance/notes, formatted and raw differences/duration, flagged, user_signed_off, notes, breaks, adjustmentReason, totalTimePerUser, sourceType, date_range_total/date_range_total_raw, and job travel/working totals.
  • Formatted duration/difference/date-range values change only when positive; zero/negative database values can remain raw. sourceType maps 1 to CRM, 2 to App, and everything else to Invalid. Net per-user/date-range totals subtract breaks.total.
  • Adjustment reason treats geolocation timestamps as seconds or milliseconds and requires an absolute 60-second time difference; without usable geo it requires stored difference >=60. It extracts known note-text keys and falls back to general notes or No reason recorded.
  • Supported 1: job fields are id, job_ref, customer_id, customer_type, meeting_time_e, date_completed, date_completed_e, customer_name, start_time, end_time, total, start_location, end_location, and vehicle_reg.
  • Job enrichment includes nondeleted jobs for the same user whose scheduled start/completed-or-estimated interval overlaps the session. Display start can use status-in-progress metadata; customer/asset names and job/user vehicle registrations are resolved in bulk. Travel total uses on-route to in-progress; working total uses effective start to completion/estimate.
  • Data rows have no explicit ORDER BY; do not assume input-ID order. There is no batch-size cap or row-ownership filter.

See it in Fieldmotion

CRM1

The Clock-ins export dialog uses this protocol and can expand overlapping jobs into export output.

CRM2

The CRM2 export first discovers IDs through UserClockins_getDataTable, then sends them to this endpoint in batches; it supplies _all_ids when full-range totals are selected.

Related endpoints