Docs · CSV schema

Account-upload CSV schema

Use this schema for bulk-uploading accounts at POST /api/creditor/upload-accounts or via the drag-and-drop uploader in the creditor dashboard. Up to 1,000 accounts per batch.

UTF-8, comma-delimited
Header row required
1,000 rows max per batch
Validates before any write

Sample · 3 rows

first_name,last_name,email,phone,principal_balance,original_creditor,charge_off_date,account_phase
Jane,Doe,jane@example.com,555-0101,5247.63,Sample Federal CU,,phase0
Robert,Martinez,rmartinez@example.com,555-0102,11500.00,Sunrise Federal CU,2025-06-22,phase1
Maria,Chen,mchen@example.com,555-0103,2800.00,Sample Federal CU,2025-04-10,phase1

⬇ Download sample CSV

Field reference

Field	Type	Required?	Notes
`consumer_email`	string	Required	Primary identifier. Consumer account is auto-created on first upload.
`original_balance`	decimal	Required	USD. Two decimals. No currency symbol.
`principal_balance`	decimal	Required	Must be ≤ `original_balance`.
`dpd`	integer	Required	Days past due at time of placement. 0–365.
`account_type`	enum	Required	One of `credit_card` · `auto_loan` · `personal_loan` · `line_of_credit`.
`account_phase`	enum	Required	`intercept` (pre-charge-off) or `recovery` (post-charge-off).
`last4ssn`	string	Optional	4 digits. Enables consumer identity match at portal sign-in.
`creditor_reference`	string	Optional	Your internal account number. Preserved on exports.
`charge_off_date`	ISO date	Optional	`YYYY-MM-DD`. Required for `intercept` phase. Computed from DPD if omitted.
`placement_date`	ISO date	Optional	Defaults to upload date.
`first_name`	string	Optional	Populates consumer greeting in portal. Not used for collection decisions.
`last_name`	string	Optional	Same.
`phone`	string	Optional	E.164 preferred (`+15125551234`). Used only with consumer opt-in.
`address_zip`	string	Optional	5-digit US ZIP. Used for time-of-day compliance (Reg F).
`last_payment_date`	ISO date	Optional	Informs the outreach-intelligence engine.
`last_payment_amount`	decimal	Optional	Same.
`minimum_payment`	decimal	Optional	Current minimum due. Shown to consumer.

Validation rules

Header row required. Column order doesn't matter.
Extra columns are ignored silently.
Missing required columns: the upload is rejected with the list of missing columns.
Row-level errors are returned individually; valid rows still persist.
principal_balance > original_balance → rejected with PRINCIPAL_EXCEEDS_ORIGINAL.
dpd > 365 or dpd < 0 → rejected with INVALID_DPD.
account_phase = intercept with dpd > 120 (credit unions) or > 180 (banks) → rejected with PHASE_MISMATCH.
Duplicate creditor_reference within the same batch → second row rejected with DUPLICATE_REFERENCE.

Example

consumer_email,original_balance,principal_balance,dpd,account_type,account_phase,last4ssn,creditor_reference
member1@example.com,5280.00,5280.00,78,credit_card,intercept,4321,ABC-00123
member2@example.com,12400.00,11800.00,148,auto_loan,recovery,,ABC-00124
member3@example.com,3200.00,3200.00,45,credit_card,intercept,7788,ABC-00125