Import File

​

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

1. 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.
2. 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.
3. 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.
4. 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. Uploaded email and mobile values stay with the imported account. They do not populate or overwrite the master consumer profile contact. When a master profile has no contact, the Consumer Portal can offer a usable email and/or mobile from linked accounts during login; the consumer must verify the chosen destination before it becomes the master profile contact. 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. The normalized SSN must contain exactly 4 or 9 digits. An Add row also fails when its uploaded email or mobile is present in the creditor company’s opt-out registry. Failed rows are written to the failed-records CSV and are not imported.

​

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. Import completion does not automatically deliver CFPB Validation Letters. The creditor must later choose a delivery method from Communications. 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. An Update import changes email or mobile on the selected account only. It does not replace the consumer’s verified master profile email or mobile. When email or mobile is selected for update, an opted-out replacement value causes that row to fail without applying the update. 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

• Add rows with an opted-out uploaded email or mobile fail before account creation. Update rows fail when a selected replacement email or mobile is opted out.
• 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 reject opted-out imported email or mobile values before creating or updating the account.
• It should keep imported account contacts separate from the consumer’s verified master profile contact.
• 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 import or update a row that supplies opted-out contact information.
• It should not overwrite a verified master profile email or mobile during an account import.
• It should not send consumer communications when the consumer lacks permission or a valid contact route.