Fieldmotion API Getting started

Customer SFTP imports

Save a customer SFTP source

POST /a/ImportCustomersFtp_save

Create or replace connection settings while preserving an existing password when blank.

When to use this endpoint

Save the source first, test its directory, then select a customer import map. Creating a source does not run it or enable 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. Source IDs and counts are restricted to the authenticated account owner; client-supplied ownership cannot expand access.

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

Parameters

ParameterTypeRequiredDescription
idInteger-compatibleYesRequired integer 0 creates; a positive integer updates an owned source. Negative, fractional and overflowing values are rejected.
typeTextYesExact ftp or sftp. Use sftp; the legacy ftp option saves but cannot connect or run.
server / directory / usernameTextYesRequired nonblank strings, maximum 255 bytes each. Saving does not test the connection.
passwordTextYesThe key must exist. A nonempty value replaces the password; blank and "0" preserve an existing value. On creation a blank value leaves no password key. There is no explicit clear-password operation.

Example request

$result = FM_api('ImportCustomersFtp_save', [
	'id'=>'0','type'=>'sftp','server'=>'imports.example.invalid',
	'directory'=>'incoming','username'=>'import-reader',
	'password'=>'replace-with-remote-password',
]);

Example response

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

Returns ok and id on creation or update. A no-change update can also include warning:"No Change."; saved=1 indicates a committed save with a failed follow-up.

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

  • Uses the required id/type/server/directory/username/password fields above. New sources default Disabled; updates preserve unrelated metadata, status and map selection. Fields accepted by the mapped writer are not forwarded by this legacy save wrapper.
  • 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. Create or Edit a source, then Save; inspect ImportCustomersFtp_save. The edit form supplies a blank password to retain it.

CRM2

In CRM2, open Imports > Customers FTP. Create/Edit a source and Save; inspect ImportCustomersFtp_save. The mapped table supplies connection fields to the editor.

Related endpoints