Fieldmotion API Getting started

Customer SFTP imports

Read a remote customer import spreadsheet

POST /a/ImportCustomersFtp_getFileAsData

Download a model spreadsheet and return raw cell values grouped by worksheet.

When to use this endpoint

Use after selecting an exact filename returned by testConnection. This previews data; it does not apply a map or import customers.

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

ParameterTypeRequiredDescription
idPositive integer or decimal integer stringYesUse the source or tenant row ID returned by its list/table. Fractions, negative numbers, arrays and out-of-range integers are rejected. This is not the import run token.
fnameExact remote basenameYesExact visible basename, maximum 255 bytes. Permitted characters are word/space/digit characters and - _ ~ , ; [ ] ( ) .; paths, repeated dots, dot-prefixed names and empty names are rejected.

Example request

$result = FM_api('ImportCustomersFtp_getFileAsData', ['id'=>'18','fname'=>'customers.csv']);

Example response

[
  [
    [
      "Name",
      "Account"
    ],
    [
      "Example customer",
      "C-1042"
    ]
  ]
]

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.
{"error": "missing or invalid parameter: id"}A required row ID is missing or invalid.
{"error": "no such entry"}The requested owned source or tenant row does not exist.
{"error": "Unable to connect to SFTP server"}The saved server cannot be connected to.
{"error": "SSH verification failed"}Password authentication failed.
{"error": "Unable to open remote directory"}The configured directory cannot be opened.
{"error": "plain FTP not yet handled"}The source uses the legacy ftp option.
{"error": "Remote file not found"}The exact visible regular file is absent.

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

Behaviour and edge cases

  • Uses saved credentials for password-authenticated SFTP on SSH port 22. Plain ftp returns "plain FTP not yet handled". There is no configurable port, private-key authentication or explicit host-key pinning in this implementation.
  • Normalizes the configured directory to an absolute SFTP path. Only qualified remote regular files are selected; hidden names, directories and symlinks are excluded. Filenames are sorted bytewise. No extension filter or paging is applied.
  • Downloads at most 32 MiB to a private temporary file, validates stable remote size/mtime, and removes the temporary file on success or failure. Expanded ZIP content is limited to 128 MiB and the loaded spreadsheet to 500000 cells.
  • Returns worksheets → rows → raw cell values, including headers and null cells. Formulas are returned as formula text. All sheets are previewed; the worker imports only the first. Empty, unreadable or invalid spreadsheets return errors rather than false.
  • Only a remote preview occurs: no map is applied and no customer or remote file is modified.

Side effects

  • Opens SSH/SFTP, reads the file and writes a local temporary copy. Does not change remote files, customer records or import history.

See it in Fieldmotion

CRM1

In CRM1, open Settings > Imports > Customers FTP. In Setup Import Map, click a remote model file; inspect ImportCustomersFtp_getFileAsData.

CRM2

In CRM2, open Imports > Customers FTP. Choose a model file in Setup Import Map; the first worksheet supplies the mapping preview.

Related endpoints