Customer SFTP imports
List the remote customer import directory
/a/ImportCustomersFtp_testConnection
Connect to a saved SFTP source and return its visible entry names.
When to use this endpoint
Use before choosing the spreadsheet used to configure the import map; an empty list means no visible entries, not an imported-file count.
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 |
|---|---|---|---|
id | Positive integer or decimal integer string | Yes | Use 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. |
Example request
$result = FM_api('ImportCustomersFtp_testConnection', ['id'=>'18']);Example response
[
"customers.csv",
"customers.xlsx"
]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. |
{"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.
- Returns a bare sorted array of visible regular-file basenames, or [] for an empty directory. There is no trailing-slash directory result. Connection, authentication and listing errors are returned as error objects; they are never treated as filenames.
Side effects
- Opens an SSH/SFTP connection and reads directory entries. Does not import customers or remove files.
See it in Fieldmotion
CRM1
In CRM1, open Settings > Imports > Customers FTP. Choose Setup Import Map; the first request is ImportCustomersFtp_testConnection.
CRM2
In CRM2, open Imports > Customers FTP. Choose Setup Import Map; inspect this call before the model-file picker.
Related endpoints
ImportCustomersFtp_save— Configure an owned source.ImportsCustomersFtp_getDataTable— Discover source rows and IDs.ImportCustomersFtp_getImportMaps— Inspect map choices before running.ImportCustomersFtp_runOnce— Understand import writes and remote cleanup.