Skip to main content

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. For example, ABC Collections chooses Medical as the Bill Type and optionally selects a hardship classification for the placement. Accounts belonging to a sub-account with its own Bill Type use that assigned type. For Add and Add + CFPB, the initial membership payment must succeed and all required setup must be complete before the CSV upload URL is issued. The same conditions are checked again before queueing an older upload session. Processing, failed, action-required, or unconfirmed payments block these new-account imports. Update and Delete retain their existing setup and authorization rules. SFTP imports also require the payment step to be complete. If you have no existing hosted accounts, your plan allows five, and you upload six valid new accounts with overflow disabled, five accounts import and the sixth appears in the failed CSV with: “Sorry, you have reached the account limit, so this consumer cannot be uploaded.” 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. Select a mapped Header Profile.
  2. Choose Add, Add + CFPB, Update, or Delete.
  3. For Add and Add + CFPB, select a Bill Type (Account Type). For Update, select the classification fields that should change.
  4. Optionally select a Financial Hardship Risk Classification and optionally check the hardship certification checkbox.
  5. Upload the CSV and review progress in Import History.
The header profile defines column mappings and date format. For an unambiguous account, Delete needs the Original Account Number. Update also needs the fields you select to change. For a shared number, include the mapped identity columns described below. Classification choices apply to the file and do not require extra CSV columns.

Date Validation

The selected Header Profile sets the order and separator for Date of Birth, Placement Date, and Self-Service Expiration Date. Use a four-digit year. During import, the system adds a leading zero to a valid one-digit month or day. For example, 6/8/1997 becomes 06/08/1997. Under MM/DD/YYYY, the importer uses June 8, 1997 to match the consumer. Under DD/MM/YYYY, it uses August 6, 1997. Add and Add + CFPB require a valid DOB for a consumer who is at least 18. Placement Date and Self-Service Expiration Date are optional. When supplied on Add, placement must be in the past and expiration must be in the future. A reimport with an omitted or blank optional date leaves that date blank. On Update, a blank date cell keeps the saved value. The failed CSV names the affected field and distinguishes a date in the wrong layout from an impossible calendar date. Under MM/DD/YYYY, 1980-02-28 uses the wrong layout and 02/30/1980 is an invalid calendar date. Valid rows still import, and you can correct and re-upload a rejected row.

Bill Type And Hardship

Bill Type classifies consumer accounts. Its 18 choices are Auto Loans, Car Insurance, Collection Accounts, Collection Legal Accounts, Federal Taxes, Garbage, Home Insurance, Medical, Mobile, Multiple, Other, Personal Loans, Small Business Loans, State Taxes, Student Loans, Telecom, Utilities, and Vet Bills. These choices remain available for imports and sub-accounts after Account Type is removed from company onboarding and Account Settings.
  • A matched sub-account’s assigned Bill Type takes precedence over the upload selection.
  • If the sub-account has no assigned type, the selected upload type applies.
  • Imported accounts keep their saved classification when the sub-account is edited later.
Financial Hardship Risk Classification is optional. No selection leaves it unclassified; Standard (No Hardship) is an explicit choice. The same selected risk applies to each successfully processed account in the file. The available choices are:
  • Standard (No Hardship)
  • Mortgage foreclosure risk
  • Vehicle repossession risk
  • Utility disconnection pending
  • Eviction risk
  • At risk of charge-off
  • Charge-off collection risk
  • Third-party collection referral risk
  • Collection litigation risk
  • Wage garnishment risk
  • Bank levy risk
  • Medical debt in collections
  • Student loan default risk
  • Federal or state tax levy risk
The hardship certification checkbox is optional for every choice. If checked, the import records who accepted it and when. Leaving it unchecked does not block the upload. For Update, unselected classification fields keep their existing values. Selecting a hardship update with no risk clears the saved risk. Delete leaves classifications unchanged.

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. The import checks for active duplicates in your portal and across other creditor portals using the Original Account Number and the consumer’s ecoAddress. The ecoAddress matches on last name, date of birth, and the last four digits of the SSN. If all four details match an active account, the failed-account report says whether it is active in your portal or another creditor’s portal. The report keeps the other creditor’s identity private. If the account number is shared by a different consumer and the row passes the other import checks, Add creates a separate account and leaves the existing account intact. If the Original Account Number and ecoAddress match a fully paid account in any creditor portal, the failed-account report shows Consumer Paid. This also applies to deactivated accounts when payment records confirm the full payoff. A partial payment alone leaves the row eligible for the remaining import checks. A match on the Original Account Number and ecoAddress also returns Consumer Disputed if a creditor portal has a recorded consumer dispute for that account. The rule still applies after deactivation or a negotiation restart. Closing a creditor account does not itself create a consumer dispute. If the Original Account Number and ecoAddress match an account the consumer previously reported as Not Paying, the failed-account report shows Consumer Reported Not Paying. The rule applies across creditor portals and after deactivation. The report keeps the previous creditor’s identity private. When the consumer restarts negotiations, the Not Paying report clears for future uploads and the usual import checks apply. Universal validation example An existing account has Original Account Number ACC-1042, last name Morgan, date of birth January 11, 1980, and SSN ending in 1234. A creditor uploads a row with that account number. If the number identifies one current record and its archived records all belong to the same consumer, Update and Delete can use the Original Account Number alone. To distinguish accounts sharing the same number, map Last Name, Date of Birth, and SSN in the Header Profile and include all three in the row. Use the profile’s date format. The file can supply the last four SSN digits or a valid full SSN, which is matched by its last four digits. For example, if Jane Morgan and Alex Reed share ACC-1042, include Jane’s last name, DOB, and SSN digits with that number. The import applies the Update or Delete only to Jane’s account if it is the sole current match. Missing, invalid, or conflicting identity details that leave the target unresolved produce a failed row. Two current accounts with the same four details also produce a failed row. Reimport example ABC Collections removed Morgan’s ACC-1042 account while it still had a balance. The account had no Paid, Disputed, or Not Paying history. ABC Collections later uploads it again with all four details matching. If the other checks pass, the account returns to New Offers. If the previous record was archived, ABC Collections can still update the balance or remove the current account using ACC-1042. If a payment for the account is still processing and the import would reopen the previous record, the failed-account report asks the creditor to retry the row after payment processing is complete. Each Add or Add + CFPB row needs at least one valid contact. You can supply an email address, a US mobile number, or both. Every supplied contact must pass its format check. For example, a row with a valid email and a blank mobile can import. If you leave both blank, the failed-account report shows Consumer Contact — Email or Mobile is required. If both are supplied and invalid, the report shows both field errors. Use a Header Profile that matches the CSV layout. If your CSV has only an Email or Mobile column, map that column in the profile. When the CSV has both columns, individual rows can leave one blank. 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. Choose one SSN mapping in the Header Profile.
  • Last Four SSN or Full Social accepts exactly four or nine digits after formatting is removed. For example, 0123 and 123-45-6789 are valid. If Excel exports 012345678 as 12345678, the importer restores the leading zero before matching or saving. Only eight plain digits qualify for this correction. Six- and seven-digit entries are rejected. An entry such as AB1234 produces SSN — Invalid format (exactly 4 or 9 digits).
  • Last 4 SSN is for a column that contains only the last four digits. If Excel exports 0001 as 1, the importer restores it to 0001 before matching or saving the account. The field accepts one to four digits. A full SSN or other text in this column produces SSN — Invalid format (1–4 digits for Last 4 SSN).
An unadded creditor invitation stays in Creditor Invitations when a valid Add or Add + CFPB row is imported for the same consumer. The imported account appears separately in New Offers. A valid Add row still reaches New Offers when the matching ecoAddress has opted out of the supplied email or mobile. The import skips all consumer email and SMS for that row. An opt-out on a different ecoAddress sharing the same contact leaves the row eligible for its normal alerts. Validation failures still go to the failed-records CSV.

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, individual pay-term offers, Bill Type, or hardship classification. 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. For Individual Offer updates, eligible rows that change the account count as applied. Valid protected rows and rows with no changes count as skipped. Invalid rows count as failed. The existing results download lists failed and skipped rows in the Errors column. Skipped messages start with Skipped:. A mixed file continues processing its eligible rows.

Delete

Delete finds the account inside the same creditor company and deactivates it. When accounts share the Original Account Number, use the identity columns to identify the 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 eligible matching accounts, leave unrelated accounts alone, and trigger the creditor-removed-account communication for consumers who can receive it. Suppose ABC Collections includes Jane’s account in that file while her $100 ACH payment is still processing. Jane’s account stays active, and her row appears in the failed CSV with Retry this row after payment processing is complete; in the Errors column. Other eligible rows still process. Once the payment settles or fails, ABC Collections can upload Jane’s row again to remove the account. If the $100 payment settled and the bank later returns it, YouNegotiate adds $100 back to the balance and marks the payment as failed. Jane’s account remains Creditor Removed.

Sub-Account IDs on Add and Add + CFPB

Use the Sub-Account ID configured under your company. When the ID matches one of your sub-accounts, the account is assigned to that sub-account. The offer uses its Pay Terms if configured and otherwise falls back to Master Pay Terms. Checkout uses the assigned sub-account’s Terms & Conditions if available and otherwise uses the Master template. Individual and Group offers retain their existing priority. On a company-level upload, a blank ID or an ID your company has not configured leaves the account at company level. The row can still import, and Master Pay Terms are the fallback. For example, if ABC Collections has a 10% Master settlement discount and its North sub-account has a 20% discount, a $1,000 account with North's ID gets an $800 offer. A blank or unconfigured ID gets a $900 offer when no Individual or Group offer applies.

Failed Account Report

For Add and Add + CFPB, the importer checks required fields and validates populated values before matching the Original Account Number, last name, date of birth, and last four SSN digits for active duplicates or Paid, Disputed, and Not Paying history. The failed CSV retains the uploaded columns, including Original Account Number when supplied, and appends an Errors column. Each invalid field gets one applicable reason. When several fields fail, semicolons separate the reasons in that cell. For example, a row with a blank account number, an invalid email, and a valid mobile can show Original Account Number — Required field missing; Consumer Email — Invalid email address; in Errors. You can correct and re-upload the rejected row while the other valid rows continue processing. To include an individual pay-term offer, supply all four fields. If you supply only one to three, the report shows Individual Pay Term Offer — Incomplete (all 4 fields required if any supplied). If all four are supplied, each invalid offer field gets its own reason. Leaving all four blank on Add or Add + CFPB uses the applicable fallback offer. Add and Add + CFPB use these field limits.

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 and Add + CFPB deliver valid accounts to New Offers. If either uploaded contact is opted out for the matching ecoAddress, the import skips the entire consumer alert, including DFA email, SMTP email, and SMS.
  • 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 require Bill Type for new-account uploads and respect assigned sub-account types.
  • It should accept uploads without hardship classification or certification.
  • It should change classifications during Update only when those fields are selected.
  • 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 create valid Add accounts with opted-out contacts and skip their alerts. It should reject opted-out contact replacements in Update rows.
  • 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.
  • While initial ACH payment processes, the creditor can finish other setup but cannot add accounts through browser uploads or SFTP. Once payment succeeds, remaining setup and existing billing, permission, and quota restrictions still apply.
  • Existing paid creditors are classified from verified payment records. Accounts without reliable initial-payment evidence remain unconfirmed.
  • Exceeding the membership allowance requires the platform Over Limit feature. When it is disabled, import only the available capacity and keep excess rows in the failed file with their reason. Pending Notice Response additions also use available capacity.
  • Save a valid membership payment method before importing extra accounts. If a file crosses the allowance without one, accounts within the allowance import and extra rows stay in the failed file with their reason. An already-full account must save a method before starting another Add import.
  • The first weekly charge for newly billable extra accounts starts when the import finishes. Existing add-on coverage is reused so the same account slots are not charged twice. New charges join an existing unpaid platform balance when applicable.

How It Should Not Work

  • It should not import consumers into the wrong creditor account.
  • It should not require certification because a hardship risk was selected.
  • It should not reset classifications during an unrelated Update or Delete import.
  • 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.
  • Suppress every consumer alert for an Add row with an opted-out contact, including any fallback to another contact or channel.
  • 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.
Last modified on November 19, 2026