Create a mapped SFTP source

When to use this endpoint

This generic CRM2 table contract differs from the owner-specific save/status editor; understand the scope and secret-handling caveats before using it.

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

Parameters

Example request

$result = FM_api('ImportCustomersFtp_createData', [
	'ownerID'=>'1042','server'=>'imports.example.invalid',
	'metaType'=>'sftp','metaDirectory'=>'incoming','metaUsername'=>'import-reader',
	'metaPassword'=>'replace-with-remote-password','status'=>'0',
]);

Example response

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

Errors and unusual responses

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

Behaviour and edge cases

• Writable fields are server, metaUsername, metaType, metaDirectory, metaPassword, status and importMap. server/username/directory/type are nonblank text up to 255 bytes; type is ftp or sftp. status is exactly 0 or 1. importMap is a positive ID of an existing customers map in this account. Blank or "0" metaPassword preserves the saved password (maximum 65535 bytes). meta accepts a JSON object/native associative array containing only username, type, directory, password and import_map; these merge with existing metadata. owner and lifecycle timestamps are server-owned; same-owner ownerID is tolerated for client compatibility. Unknown top-level fields are ignored.
• New sources derive their owner and timestamps from the authenticated account and default to Disabled. A supplied valid status can override that default on the mapped create route. Updates stamp last_edited only when data changes and preserve unrelated saved metadata.
• All target IDs are checked before a bulk write. A missing/foreign row or invalid field rejects the whole transaction, preserving earlier rows. No-change mapped updates return {ok:1,warning:"No Change."}. No oldData or credentials are returned.
• Every path reconciles features_used bit 8 from whether this account has any nonzero-status source, preserving unrelated bits. Source creation, update and bookkeeping commit together. This marker is usage bookkeeping, not an entitlement check.
• Checked database writes roll back within their database transaction. Global source settings and tenant audit writes are separate commits: saved=1 with a warning means the setting was saved but a follow-up failed. Inspect the saved state; do not blindly repeat a write.
• Saving settings does not contact the remote server, run an import or validate a spreadsheet. Passwords remain in saved metadata; response and audit redaction does not provide encryption at rest.

Side effects

• Writes global source configuration and timestamps, reconciles the usage marker, invalidates source cache and records a tenant audit with passwords removed. No customer import or notification.

See it in Fieldmotion

CRM1

In CRM1, open Settings > Imports > Customers FTP. No direct mapped-writer caller was found; CRM1 uses save and setStatus.

CRM2

In CRM2, open Imports > Customers FTP. The table is configured with this singular API prefix, but source creation is overridden to use save; no direct createData UI action was found.

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.