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

consumer_email,original_balance,principal_balance,dpd,account_type,account_phase,last4ssn,creditor_reference
jane@example.com,5247.63,5247.63,78,credit_card,intercept,4321,ABC-00123
rmartinez@example.com,11500.00,11000.00,148,auto_loan,recovery,,ABC-00124
mchen@example.com,2800.00,2800.00,45,credit_card,intercept,7788,ABC-00125

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. Recorded for reference; not used for Reg F time-of-day compliance, which is derived from the consumer's state, not ZIP.
`debtor_state`	string	Optional	2-letter US state code. Drives Reg F §1006.6 inconvenient-time-of-day determination for outreach to this consumer. Omitting it does not block placement, but outreach timing falls back to the Eastern time zone default until a state is on file.
`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 beyond the creditor's configured charge_off_dpd_threshold (the NCUA 120-day boundary for credit unions; the creditor's own configured threshold for other creditors) → 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