Skip to main content

​
Real-World Example

ABC Collections sends consumer placement files to an SFTP folder every night. The creditor configures the SFTP connection once in the portal, attaches it to a mapped Header Profile, and then drops files into the expected folders. When the scheduled import runs, YouNegotiate connects to the SFTP server, finds the CSV files, copies each file into the same import storage used by manual uploads, creates import history, and processes the file through the standard consumer-import queue.

​
Visual Flow

​
Folder Layout

SFTP import uses the configured import_filepath, then the Header Profile name, then one folder per import type.
Update can also use more specific update folders. The app reads folders that start with update and can parse selected update fields from names such as:

​
Schedule

The SFTP import command is scheduled in the Laravel kernel:
  • Command: import-consumers:via-sftp
  • Time: twice daily at 10:00 AM and 6:00 PM
  • Timezone: America/New_York
  • Safety: concurrent run protection and single-server execution

​
What Must Exist Before SFTP Import Works

  • The SFTP connection must be enabled.
  • The connection must have an import filepath.
  • A Header Profile must be mapped and linked to the SFTP connection.
  • The creditor company must have an active membership.
  • The creditor setup wizard must be complete.
  • The file must be a CSV and must live in the correct import-type folder.

​
What Happens To Files

  1. The command scans the expected folders for .csv files.
  2. Each CSV is copied into local import_consumers storage.
  3. A file_upload_histories record is created with is_sftp_import.
  4. The same Import Consumer Processing pipeline handles chunking, validation, row processing, finalization, and communications.
  5. The remote source file is moved into a proceed folder.
  6. If a failed-records CSV is available, it is copied into a failed folder beside the source folder.

​
Relationship To Manual Import

SFTP is an automated pickup method. Manual import is a browser upload method. After the file is stored and import history is created, both use the same background jobs. See Import File for the manual upload flow and Import Consumer Processing for the shared queue behavior. For the email/SMS delivery and webhook side of those import-triggered communications, see Communication Delivery & Webhooks.

​
How It Should Work

  • It should let authorized creditor users configure secure file transfer details.
  • It should import only from enabled SFTP connections linked to mapped Header Profiles.
  • It should process Add, Add + CFPB, Update, and Delete folders according to the same import rules used by manual upload.
  • It should preserve failed row details and return failed files to the SFTP failed folder.
  • It should not require a user to keep the portal open while files process.

​
How It Should Not Work

  • It should not expose connection credentials to unauthorized users.
  • It should not import files from a disabled connection.
  • It should not process files for a creditor whose setup wizard is incomplete.
  • It should not import files from the wrong Header Profile folder.
  • It should not leave processed remote files sitting in the active import folder.

​
Developer Notes

  • SFTP credentials are used through Laravel’s SFTP filesystem driver at command runtime.
  • SFTP imports skip empty CSV files.
  • Add and Add + CFPB SFTP files still enforce membership limits and over-limit rules.
  • SFTP import history uses uploaded_by = null because the file is picked up by the scheduled command.
  • Failed files are generated locally by the chunk processor and copied back to SFTP by GenerateErrorFileOfImportedConsumersViaSFTPJob when a failed file is available.
  • app/Livewire/Creditor/SftpConnection
  • app/Console/Commands/ImportConsumersViaSFTPCommand.php
  • app/Console/Kernel.php
  • app/Enums/FileUploadHistoryType.php
  • app/Enums/ConsumerUpdateFields.php
  • app/Jobs/ImportConsumersCoordinatorJob.php
  • app/Jobs/GenerateErrorFileOfImportedConsumersViaSFTPJob.php
Last modified on May 27, 2026