Save a reusable import map · Fieldmotion API

When to use this endpoint

Save the mapping before running an import. Omit id for creation; id=0 is an update lookup, not a create sentinel.

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.

Saving a new row requires Add; supplying an existing ID requires Edit. Reusing an existing same-name mapping also requires Edit.

Parameters

Parameter	Type	Required	Description
`type`	Text	Yes	Text up to 64 bytes; no type enum. customers runs the existing legacy mainFormat custom-field hook. A map referenced by an SFTP source cannot change import type.
`mappings`	Native array/object or JSON text	Workflow-required	Native array/object or valid JSON decoding to an array/object. Entries are destination strings or row descriptors with a string to field. SFTP specifically requires heading → allowed-destination pairs; generic maps can serve other import flows. Invalid JSON/entries are rejected before writes.
`name`	Text	No	Maximum 64 bytes. Omitted creation defaults blank; omitted update retains the name. Explicit names rename in place. Duplicate name/type collisions and ambiguous legacy duplicates are rejected.
`id`	Positive integer or decimal integer string	Yes	Omit to create or reuse the existing unique name/type map. A supplied ID must be positive and exist; zero is not creation. Existing map identity is preserved.
`import_id`	Integer-compatible source ID	No	Optional positive account-owned SFTP source ID; omission/0 makes no association. Requires FTP Imports View/Edit and customers type. Source ownership is validated before map persistence.

Example request

$result = FM_api('ImportMappings_save', [
	'type'=>'customers','name'=>'Customers by name',
	'mappings'=>json_encode(['Name'=>'name','Account'=>'account_number']),
	'import_id'=>'18',
]);

Example response

{
  "ok": 1,
  "id": 8
}

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 import map"}`	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

Updates/renames in place, preserving ID, creation time and source references. A unique existing name/type is reused rather than deleted/recreated. An unchanged save without a source returns {warning:"no change needed"}.
An unchanged map with import_id still attempts association. Association updates only this account’s source and its last_edited, preserving saved credentials and other metadata. It rechecks that the selected customers map exists.
Tenant map/audit/custom-field changes share one checked transaction. The global source association commits separately: a failure returns ok/id, saved=1 and an explicit association warning. Select the saved map again; do not create another map.
For customers maps, legacy custom[Name] destinations add missing fields to the final existing mainFormat page and update the existing setting rather than inserting duplicates. If no legacy mainFormat exists, no layout is created. This hook does not convert modern layouts or migrate existing customer custom values.

Side effects

Writes the tenant map and audit, invalidates mapping cache, and may update/invalidate legacy customer layout settings. An import_id can update global source metadata with a redacted tenant audit. Does not import records or access remote files.

See it in Fieldmotion

CRM1

In CRM1, save a file-import map or a Customers FTP > Setup Import Map selection; inspect ImportMappings_save. FTP setup passes import_id; ordinary file imports pass zero.

CRM2

CRM2 uses the same save route in file-import dialogs and Customers FTP Setup Import Map; bulk map inspection/removal is on Imports > Mappings.

Related endpoints

ImportMappings_getAll — Load a type-specific selector.
ImportCustomersFtp_getImportMaps — Read a source’s selected map.