Page mapped customer SFTP sources

When to use this endpoint

Use for CRM2 source management. Request only the fields needed by the screen and treat metadata as private.

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 pageImportsCustomersFtp. Source IDs and counts are restricted to the authenticated account owner; client-supplied ownership cannot expand access.

Parameters

Parameter	Type	Required	Description
`fields`	Native string array	Yes	Mapped field names, not a JSON string. id is always appended. Unknown names are silently omitted; an empty list still selects id.
`start / length / draw`	Integer-compatible	No	Defaults 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 / limit`	Integer-compatible	No	Default table mode. isTable=0 returns only data, ignores start/length and removes counts. A positive limit caps unpaged results; zero means unlimited.
`orderBy / orderDesc / order`	Mapped name / direction / native array	No	Mapped 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 / searchField`	Text / mapped name or native list	No	Nonblank searchValue searches mapped fields; searchField defaults All. Substring matching is case-insensitive and SQL LIKE wildcards retain their meaning.
`Mapped field filters`	Scalar/native list	No	Mapped 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 / dateTo`	Mapped field / relative integer days	No	A 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 / offsetTo`	Native {hour,minute}	No	Legacy boundary adjustments: hour is negated and minute added. Not applied to date-only fields. These are offsets, not timezone names.
`timeRangeFrom / timeRangeTo`	Integer hours	No	With 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 / advanceSearch`	Native arrays	Legacy controls	Nonempty 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('ImportsCustomersFtp_getDataTable', [
	'fields'=>['id','server','status','metaDirectory','metaType'],
	'start'=>'0','length'=>'10','orderBy'=>'id','orderDesc'=>'asc',
]);

Example response

{
  "data": [
    {
      "id": "18",
      "server": "imports.example.invalid",
      "status": "0",
      "metaDirectory": "incoming",
      "metaType": "sftp"
    }
  ],
  "draw": 0,
  "recordsTotal": "1",
  "recordsFiltered": "1"
}

Errors and unusual responses

Response	Condition
`{"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.
Whole meta is returned as encoded JSON with password removed. Requesting meta or metaPassword adds hasPassword; metaPassword itself is always blank. Password and whole-meta filters/search/sorts are rejected, and All search excludes metadata.

Side effects

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

See it in Fieldmotion

CRM1

In CRM1, open Settings > Imports > Customers FTP. Uses the positional ImportsCustomersFtp_getDT instead.

CRM2

In CRM2, open Imports > Customers FTP. Load Imports > Customers FTP; widgetDisplayStyle requests this mapped table with connection fields needed by its custom editor.

Related endpoints

ImportCustomersFtp_save — Configure an owned source.
ImportCustomersFtp_getImportMaps — Inspect map choices before running.
ImportCustomersFtp_runOnce — Understand import writes and remote cleanup.