Fieldmotion API Getting started

Import mappings

Page mapped import mapping records

POST /a/ImportMappings_getDataTable

Return named fields and shared filters for CRM2’s Mappings screen.

When to use this endpoint

Use for table viewing/search. getAll is simpler when selecting maps for one import type.

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 pageImportsMappings. 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('ImportMappings_getDataTable', ['fields'=>['id','name','importType','mappings','cDate'],'start'=>'0','length'=>'10']);

Example response

{
  "data": [
    {
      "id": "8",
      "name": "Customers by name",
      "importType": "customers",
      "mappings": "{\"Name\":\"name\"}",
      "cDate": "1793872800"
    }
  ],
  "draw": 0,
  "recordsTotal": "1",
  "recordsFiltered": "1"
}

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.
  • Mappings cDate is returned as raw Unix seconds but uses Unix-aware relative date filtering.

Side effects

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

See it in Fieldmotion

CRM1

CRM1 uses ImportMappings_getDT for this screen.

CRM2

Load CRM2 Imports > Mappings or change table filters; widgetDisplayStyle uses plural prefix ImportMappings and requests getDataTable.

Related endpoints