> ## Documentation Index
> Fetch the complete documentation index at: https://docs.younegotiate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SFTP Connections

> ABC Collections sends consumer import files to an SFTP folder, and YouNegotiate picks them up on a schedule.

## 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

```mermaid placement="top-right" actions={true} theme={"system"}
flowchart TD
    A["Creditor saves SFTP connection"] --> B["Connection is attached to mapped header profile"]
    B --> C["Creditor places CSV in SFTP folder"]
    C --> D["Scheduled command runs twice daily"]
    D --> E{"Connection enabled and setup complete?"}
    E -->|No| F["Skip this company or connection"]
    E -->|Yes| G["Scan add, add+cfpb, update, and delete folders"]
    G --> H["Copy CSV to import_consumers"]
    H --> I["Create SFTP import history"]
    I --> J["Run standard import chunk pipeline"]
    J --> K["Move source file to proceed"]
    J --> L{"Failed rows?"}
    L -->|Yes| M["Upload failed CSV to SFTP failed folder"]
    L -->|No| N["No failed file returned"]
    classDef default fill:#F8FAFC,stroke:#64748B,stroke-width:1.5px,color:#0F172A;
    classDef actor fill:#E0F2FE,stroke:#0284C7,stroke-width:2px,color:#0C4A6E;
    classDef system fill:#F8FAFC,stroke:#64748B,stroke-width:1.5px,color:#0F172A;
    classDef decision fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F;
    classDef risk fill:#FEE2E2,stroke:#DC2626,stroke-width:2px,color:#7F1D1D;
    classDef outcome fill:#DCFCE7,stroke:#16A34A,stroke-width:2px,color:#14532D;
    class A,C actor;
    class B,D,G,H,I,J,K,N system;
    class E,L decision;
    class F,M risk;
    class K,N outcome;
    linkStyle default stroke:#94A3B8,stroke-width:2px;
```

## Folder Layout

SFTP import uses the configured `import_filepath`, then the Header Profile name, then one folder per import type.

```text theme={"system"}
{import_filepath}/{header_profile_name}/add-new
{import_filepath}/{header_profile_name}/add-new+cfpb
{import_filepath}/{header_profile_name}/update
{import_filepath}/{header_profile_name}/delete
```

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:

```text theme={"system"}
update-email
update-mobile
update-balance
update-expiry
update-terms
update-email-mobile
```

## 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](/portals/creditor/import-export/csv-and-sftp-import-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](/portals/creditor/import-export/import-file) for the manual upload flow and [Import Consumer Processing](/portals/creditor/import-export/csv-and-sftp-import-processing) for the shared queue behavior.

For the email/SMS delivery and webhook side of those import-triggered communications, see [Communication Delivery & Webhooks](/portals/creditor/background-processing/communication-delivery-and-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.

## Related App Areas

* `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`