Import File - YouNegotiate Docs

Real-World Example

ABC Collections receives a 12,000-row placement file from a client. The creditor first creates or selects a Header Profile so the portal knows which CSV column means account number, balance, name, date of birth, phone, email, expiration date, pay-term fields, and other consumer fields. Then the creditor chooses the import type:

Import Type	Real-World Use
Add	Add new consumer accounts into the creditor portal.
Add + CFPB	Add new consumer accounts and place that uploaded file into the CFPB Validation Letter workflow.
Update	Update selected fields on existing consumer accounts, such as email, mobile, balance, expiration date, or individual pay-term offers.
Delete	Remove accounts from active collections by deactivating matching consumers.

If 11,940 rows are valid and 60 rows have problems, the valid rows should still process. The 60 bad rows should be written to a failed-records CSV with an Errors column so the creditor can fix and re-upload them.

Visual Flow

Manual Import Steps

Create or select a Header Profile. The header profile stores the creditor’s CSV header names, mapped YouNegotiate fields, and date format. The same mapping can be reused for future uploads and SFTP imports.
Upload the consumer CSV. The portal reads the first row, checks that the file headers match the selected profile, and blocks the import if the headers do not match. For Delete imports, only the account number mapping is needed. For Update imports, account number is required and the creditor chooses which fields should be updated.
Choose the import type. Add and Add + CFPB can create new active accounts. Update only changes existing accounts for the same creditor. Delete only deactivates existing accounts for the same creditor.
Let the background jobs finish. After upload, the browser should not do all row processing. The app stores the file, creates import history, and uses queued jobs to process the rows in chunks.

Import Type Behavior

Add

Add creates active consumer accounts for the creditor. For each valid row, the app stores the uploaded SSN on the account row and checks the consumer identity by last name, date of birth, and the final four SSN digits. If a matching consumer profile already exists, the new account reuses that profile so the same person can have multiple creditor accounts without creating duplicate profile records. Example: Jane Doe already has a profile from an older ABC Collections account. A new Add file contains Jane’s same last name, date of birth, and full SSN with a new account number. The import should create the new account, preserve the full account SSN for reporting, and connect it to Jane’s existing profile using the final four SSN digits.

Add + CFPB

Add + CFPB does the same account creation work as Add, then marks that upload as a CFPB-capable file. After the import completes, the creditor can use the CFPB Validation Letter area to download letters or send secure EcoLetters. When secure EcoLetters are sent, the app creates the consumer e-letter records and triggers the CFPB delivery email/SMS communication flow for consumers who are allowed to receive messages.

Update

Update finds an existing consumer by account number inside the same creditor company. It should not create a new account if the account number is missing or unknown. The creditor can limit the update to selected fields: email, mobile phone, balance, expiration date, or individual pay-term offers. If pay-term fields are included, all required pay-term columns must be mapped together so the offer math stays consistent. Example: ABC Collections uploads an Update file for Jane’s account that changes the monthly payment minimum and first-payment due window. The account remains the same, but the consumer’s available offer should refresh. If the pay terms changed, the app queues a consumer notification about the updated account offer.

Delete

Delete finds an existing consumer by account number inside the same creditor company and deactivates that account. It also cancels failed or scheduled transactions for that account. Example: ABC Collections receives a recall file for 300 accounts. The Delete import should deactivate those 300 matching accounts, leave unrelated accounts alone, and trigger the creditor-removed-account communication for consumers who can receive it.

Chunking And Storage

The uploaded CSV is stored under import_consumers.
The app creates a file_upload_histories record with status In-Progress.
Manual uploads run CalculateTotalRecordsJob first, then ImportConsumersCoordinatorJob.
The coordinator reads non-blank CSV rows and creates one consumer_import_chunks record per 500 rows.
Each chunk is processed by ProcessConsumerChunkJob on the imports queue.
Chunk jobs batch database writes in smaller groups, record failed rows, and update processed/failed counts.
When all chunks finish, FinalizeConsumerImportJob aggregates the counts and marks the upload Completed or Failed.

Email, SMS, And Follow-Up Work

New Add imports can queue new-account communications after the import is finalized.
Add rows that reuse an existing PII profile can queue the existing-account communication path.
Update rows that change individual pay-term offers can queue an updated-offer communication.
Delete rows dispatch the removed-account communication after consumers are deactivated.
Email/SMS delivery still respects consumer permissions, opt-outs, valid contact checks, and the automated communications feature flag.
Large completed Add or Add + CFPB uploads can send a completion email to the configured creditor user when the upload reaches the configured large-file threshold.

For provider delivery, open tracking, SMS opt-out replies, and webhook callbacks, see Communication Delivery & Webhooks.

SFTP Uses The Same Processing

Manual imports and SFTP imports meet at the same queue pipeline after the file is stored and import history is created. See Import Consumer Processing for the shared background processing details, and SFTP Connections for the scheduled SFTP pickup rules.

How It Should Work

It should require a mapped header profile before processing real consumer rows.
It should keep each import scoped to the creditor company and sub-account that owns the upload.
It should process large files through queued chunk jobs, not one long web request.
It should keep failed row details available from import history.
It should preserve consumer communication permissions when sending email/SMS.

How It Should Not Work

It should not import consumers into the wrong creditor account.
It should not accept files whose headers do not match the selected header profile.
It should not create new accounts during an Update import.
It should not silently ignore failed rows.
It should not send consumer communications when the consumer is opted out or has no valid contact route.

Developer Notes

Add and Add + CFPB enforce membership upload limits and over-limit rules before processing.
If any pay-term offer column is present, the required pay-term offer columns must be mapped together.
Failed rows are appended to a failed-records CSV with the original row data plus an Errors column.
Finalization also handles over-limit billing for Add imports and subscription slot syncing after Delete imports.

app/Livewire/Creditor/ImportConsumers/UploadFilePage.php
app/Livewire/Creditor/ImportConsumers/MapUploadedFilePage.php
app/Livewire/Creditor/ImportConsumers/IndexPage.php
app/Enums/FileUploadHistoryType.php
app/Jobs/CalculateTotalRecordsJob.php
app/Jobs/ImportConsumersCoordinatorJob.php
app/Jobs/ProcessConsumerChunkJob.php
app/Jobs/FinalizeConsumerImportJob.php
app/Jobs/ProcessConsumerImportNotificationsJob.php
app/Jobs/ImportDeactivatedConsumersJob.php

​Real-World Example

​Visual Flow

​Manual Import Steps

​Import Type Behavior

​Add

​Add + CFPB

​Update

​Delete

​Chunking And Storage

​Email, SMS, And Follow-Up Work

​SFTP Uses The Same Processing

​How It Should Work

​How It Should Not Work

​Developer Notes

​Related App Areas