Fieldmotion API Getting started

Customer SFTP imports

List maps for a customer SFTP source

POST /a/ImportCustomersFtp_getImportMaps

List reusable customer maps and the source’s currently selected map ID.

When to use this endpoint

Call after downloading a model spreadsheet, then use ImportMappings_save with import_id to associate a chosen map.

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.

Also requires View on pageImportsMappings.

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.

Example request

$result = FM_api('ImportCustomersFtp_getImportMaps', ['id'=>'18']);

Example response

{
  "maps": [
    {
      "id": "8",
      "name": "Customers by name",
      "mappings": "{\"Name\":\"name\",\"Account\":\"account_number\"}"
    }
  ],
  "selected": 8
}

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.

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 all tenant customers maps ordered by name then ID. mappings remains JSON-encoded text. There is no pagination or cap.
  • selected is the saved import_map value without conversion, or an empty string when absent. Legacy stale relationships may still be visible, but saving an association and running an import validate that the selected customers map exists.
  • Does not read passwords, spreadsheets or customer records.

Side effects

  • Reads data without modifying import settings, imported records, history, queues or notifications.

See it in Fieldmotion

CRM1

In CRM1, open Settings > Imports > Customers FTP. Choose Setup Import Map, then a model file; inspect ImportCustomersFtp_getImportMaps.

CRM2

In CRM2, open Imports > Customers FTP. Choose Setup Import Map and a remote file; the same request populates the map selector.

Related endpoints