Fieldmotion API Getting started

Import history

Page mapped import history records

POST /a/ImportHistory_getDataTable

Return named run identifiers, counts, users and uploaded filenames.

When to use this endpoint

Use for CRM2 import history or to find the log row ID associated with a manual import’s metadata token.

Authentication and permissions

Use signed API-key authentication or a logged-in CRM session. API keys act as their owner; session requests use dispatcher CSRF protection when configured.

Requires a valid tenant account and View on pageImportsHistory. Reads and writes use this account’s tenant tables.

Parameters

ParameterTypeRequiredDescription
fieldsNative string arrayYesMapped field names, not a JSON string. id is always appended. Unknown names are silently omitted; an empty list still selects id.
start / length / drawInteger-compatibleNoDefaults 0/10/0. Nonnegative integer offset/draw and positive page size; negative or malformed controls are rejected. No all-record length=-1 sentinel or maximum page size.
isTable / limitInteger-compatibleNoDefault table mode. isTable=0 returns only data, ignores start/length and removes counts. A positive limit caps unpaged results; zero means unlimited.
orderBy / orderDesc / orderMapped name / direction / native arrayNoMapped names only; named ordering uses orderBy and orderDesc together. Directions must be asc or desc. Legacy order[0].column minus one (clamped at zero) selects a projected field. Table-mode ordering adds an ID tie-breaker. Unpaged mode retains shared referenceDate ordering.
searchValue / searchFieldText / mapped name or native listNoNonblank searchValue searches mapped fields; searchField defaults All. Substring matching is case-insensitive and SQL LIKE wildcards retain their meaning.
Mapped field filtersScalar/native listNoMapped filters combine with AND: text scalars use substring LIKE matching; native lists use IN. id filters the mapped ID; ids is also a validated native/JSON list of positive IDs (empty list selects none). Unknown mapped names are omitted. Owner controls cannot expand SFTP account scope.
referenceDate / dateFrom / dateToMapped field / relative integer daysNoA recognized referenceDate plus both relative offsets adds an inclusive start-midnight/end-23:59:59 range. Today uses the account timezone setting (fallback UTC). datetimeUnix fields compare stored seconds against converted time boundaries; other fields compare their stored values with formatted date boundaries.
offsetFrom / offsetToNative {hour,minute}NoLegacy boundary adjustments: hour is negated and minute added. Not applied to date-only fields. These are offsets, not timezone names.
timeRangeFrom / timeRangeToInteger hoursNoWith referenceDate, supplying the lower hour activates inclusive hour filtering; upper defaults 23 and reversed bounds swap. Upper alone does not activate it. Uses timezone setting, fallback Europe/London.
groupBy / advanceSearchNative arraysLegacy controlsNonempty groupBy is rejected as unsupported grouping. Native structured search rules are validated. Rules use column (or id), condition and value, with equal, contains, notEqual, greaterThan, greaterThanOrEqual, lesserThan or lesserThanOrEqual; andOr is AND/OR. Raw where fragments, unknown columns, invalid operators and malformed lists are rejected. Counts describe records.

Example request

$result = FM_api('ImportHistory_getDataTable', [
	'fields'=>['id','importID','importType','numItemsCreated','numItemsEdited','metaFileName','cDate'],
	'start'=>'0','length'=>'10','orderBy'=>'id','orderDesc'=>'desc',
]);

Example response

{
  "data": [
    {
      "id": "312",
      "importID": "179387280001",
      "importType": "6",
      "numItemsCreated": "2",
      "numItemsEdited": "0",
      "metaFileName": "assets.csv",
      "cDate": "2026-11-05 10:00:00"
    }
  ],
  "draw": 0,
  "recordsTotal": "12",
  "recordsFiltered": "12"
}

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": "permission denied"}The user lacks the required Imports page action.

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

Behaviour and edge cases

  • Returns the mapped data/count envelope shown below. Table mode defaults to ten rows; isTable=0 returns data without counts, with optional positive limit. Unknown projected names are omitted and id is appended.
  • Search and filters are validated before entering the shared mapped query builder. Account scope also applies to SFTP total counts; an ID selection changes the filtered count, not the scoped total. Numeric/date controls and sort directions reject malformed values.
  • History cDate is a formatted datetime projection of its stored Unix seconds. ImportID is the run token; id is the log-row ID used for selection/removal.

Side effects

  • Reads rows only. No imports, configuration changes, customer writes, deletions or emails.

See it in Fieldmotion

CRM1

CRM1 uses ImportHistory_getDT; that positional contract has no filename/user projection.

CRM2

Load CRM2 Imports > History, filter Created Date or File Name, and inspect ImportHistory_getDataTable. Filename regression coverage verifies the asset-upload path.

Related endpoints