For all optional fields where you do not plan to pass through data, please include the header and an empty value.
credit or deposit.
IDs & Details
| Field | Description | Required | Data Type |
|---|---|---|---|
| account_id | Unique ID of the account. Accounts need to exist and be uploaded to Lead. | Required | string |
| client_balance_id | Client-generated unique ID of the balance. This field should be populated only if the balance was initially created via a file workflow. If the balance was created via API, this field should be left blank. Lead uses this ID to reconcile day-over-day changes to balance, and a given balance should have a single ID across its lifecycle. | Required if the balance was created via a file workflow | string |
| id | Lead-generated unique ID of the balance. This field should be populated with the server-generated ID returned from a Create Subledger Balance API call. If the balance was not created via API, this field should be left blank. Lead uses this ID to reconcile day-over-day changes to balance, and a given balance should have a single ID across its lifecycle. | Required if the balance was created via an API workflow | string |
| client_balance_name | A name that is used to identify the product or balance being reported (e.g., Rainy Day Fund). | Required | string |
| client_settlement_bank_account_id | ID of the underlying settlement bank account where funds for the balance_id are held. | Required for programs with balances held across multiple FBOs and Banks | enum (these will be provided by Lead during your implementation) |
Status & Timing
| Field | Description | Required | Data Type |
|---|---|---|---|
| created_at | Datetime the Balance was initiated. | Required | datetime ISO8601 |
| status | See Balance Statuses for more detail. | Required | enum |
| status_reason | See Balance Statuses for more detail. | Required | enum |
| type | Possible enums: deposit, credit. | Required | enum |
Balance Activity
| Field | Description | Required | Data Type |
|---|---|---|---|
| balance | End customer’s available balance as of the report’s effective date/time. For credit products, Lead will validate that balance = outstanding_principal + outstanding_interest + outstanding_fees. | Required | number currency decimals |
| currency | The currency in which the balance is denoted. | Required | ISO04217 |
| balance_in_usd | Balance in USD | Required if the program can have non-USD balances | number |
| outstanding_principal | The outstanding balance allocated to principal. | Required if type = credit | number currency decimals |
| outstanding_interest | The outstanding balance allocated to interest. | Required if type = credit | number currency decimals |
| outstanding_fees | The outstanding balance allocated to fees. | Required if type = credit | number currency decimals |
Rewards Balance
| Field | Description | Required | Data Type |
|---|---|---|---|
| rewards_balance | The cumulative rewards accrued that have not been paid out on this account. | Required for reward-offering products | number decimal(M, 2) E.g., 11.50 |
| rewards_unit | The unit of the rewards accrued. Possible enums: usd, points. | Required for reward-offering products | enumusdpoints |
Dispute Balance
| Field | Description | Required | Data Type |
|---|---|---|---|
| dispute_balance | The cumulative amount that is under dispute. This amount under dispute should not appear in balance. For credit products, Lead will validate that dispute_balance = dispute_principal + dispute_interest + dispute_fees. | Required | currency decimals; amount should be 0 or positive |
| dispute_principal | The dispute balance allocated to principal. This amount is cumulative. | Required if type = credit | currency decimals; amount should be 0 or positive |
| dispute_interest | The dispute balance allocated to interest. This amount is cumulative. | Required if type = credit | currency decimals; amount should be 0 or positive |
| dispute_fees | The dispute balance allocated to fees. This amount is cumulative. | Required if type = credit | currency decimals; amount should be 0 or positive |
Charge Off Balance
| Field | Description | Required | Data Type |
|---|---|---|---|
| charge_off_balance | The cumulative amount charged off. This amount should not appear in balance. For credit products, Lead will validate that charge_off_balance = charge_off_principal + charge_off_interest + charge_off_fees. | Required | currency decimals; amount should be 0 or positive |
| charge_off_principal | The charge-off balance allocated to principal. This amount is cumulative. | Required if type = credit | currency decimals; amount should be 0 or positive |
| charge_off_interest | The charge-off balance allocated to interest. This amount is cumulative. | Required if type = credit | currency decimals; amount should be 0 or positive |
| charge_off_fees | The charge-off balance allocated to fees. This amount is cumulative. | Required if type = credit | currency decimals; amount should be 0 or positive |
Past Due Balance
| Field | Description | Required | Data Type |
|---|---|---|---|
| past_due_balance | Applicable to credit products only: balance past due. This amount is cumulative and must always be equal to or less than balance. If a credit balance is both past due and charged off, the amount should only be included in charge_off_balance and not in past_due_balance. Note past_due_balance = past_due_principal + past_due_interest + past_due_fees. | Required if type = credit | currency decimals; amount should be 0 or positive |
| past_due_days | Applicable to credit products only: The number of days the balance is past due. Must be greater than 0 if past_due_balance is greater than 0. | Required if past_due_balance > 0 | integer |
| past_due_principal | Applicable to credit products only: The past due balance allocated to principal. This amount is cumulative. | Required if past_due_balance > 0 | currency decimals; amount should be 0 or positive |
| past_due_interest | Applicable to credit products only: The past due balance allocated to interest. This amount is cumulative. | Required if past_due_balance > 0 | currency decimals; amount should be 0 or positive |
| past_due_fees | Applicable to credit products only: The past due balance allocated to fees. This amount is cumulative. | Required if past_due_balance > 0 | currency decimals; amount should be 0 or positive |
Interest Rate
| Field | Description | Required | Data Type |
|---|---|---|---|
| interest_rate | For deposit products, this field represents the annualized interest rate offered to customers on this balance. For credit products, this field represents the interest rate disclosed to the borrower for this balance. | For deposit products, required if the product accrues interest. For credit products, required if type = credit AND is_interest_based = true | For deposit products, decimal(M, 6). E.g., 11.500000% interest rate reported as 11.500000. For credit products, decimal(M, 3). E.g., 11.500% interest rate reported as 11.500. |
Interest Accrued Balance
| Field | Description | Required | Data Type |
|---|---|---|---|
| interest_accrued_balance | Applicable to deposit products only: The cumulative interest accrued that has not been paid out on this balance. This should be in the same currency as the deposit balance. | Required for deposit programs with interest | For deposit programs with interest, value is a number with minimum currency decimals (e.g., if currency is USD, value must be at least 2 decimal places, 11.500) |
| interest_accrued_balance_in_usd | Applicable to deposit products only: The cumulative interest accrued balance (in USD) that has not been paid out on this account. | Required for deposit programs with interest and if your customers can hold non USD balances | number Minimum 2 decimals, 11.50 or 11.500 |
Credit Details
| Field | Description | Required | Data Type |
|---|---|---|---|
| structure | Indicates whether the credit product represented by this balance allows funds to be redrawn after repayment. Possible enums: - revolving: Used for products where the available credit replinishes as the borrower makes repayments. Common examples include credit cards and revolving lines of credit. Borrowers can draw, repay, and draw again, up to the credit limit.- non_revolving: Used for products where funds can only be drawn once (or up to a pre-set number of draws) and repayments do not increase available credit. A common example is a term loan product. | Required if the balance was created via an API workflow | enum |
| expected_maturity_date | The expected maturity date of the loan. | Required for non-revolving credit products | date YYYY-MM-DD |
| repayment_details | Repayment details for the credit balance | Required if expected_maturity_date is present and the balance was created via a file workflow.Required if type = credit and the balance was created via an API workflow. | Array of JSON objects Repayment details: expected_payment_frequency: “weekly, biweekly, monthly, every_thirty_days, maturity” (required) expected_number_of_payments: “integer” (optional) expected_first_payment_date: “YYYY-MM-DD” (required) expected_first_payment_amount: “currency decimals” (optional) expected_last_payment_date: “YYYY-MM-DD” (optional) expected_last_payment_amount: “currency decimals” (optional) expected_payment_amount: “currency decimals” (optional) |
| is_interest_based | Indicates whether the credit balance is interest-based. | Required if type = credit | boolean |
| effective_apr | The APR as disclosed to the borrower. If the product is fee-based, please include the fee amount in your calculation of this field. | Required if type = credit | number decimal(M,3). E.g., 11.520% APR reported as 11.520 |
| effective_interest_rate | The true annualized cost of borrowing to the borrower, taking into account the interest rate and impact of compounding. This is the actual annualized accrual rate you apply to the balance for interest accrual during a period. | Required if type = credit and the balance was created via an API workflow | number decimal(M,6). E.g., 9.123456% effective interest rate reported as 9.123456 |
| expected_finance_charge_amount | The total expected finance charge if the customer pays according to the loan schedule. | Required if expected_maturity_date is present and the balance was created via a file workflow.Required if type = credit, structure = non_revolving, and the balance was created via an API workflow. | number currency decimals |
| autopay_method | Autopay Method enum (ach, debit_card, wire, virtual_wallet, credit_card,none) | Required if type = credit | enum |
| max_funding_amount | The maximum amount of funding that will be requested for this non-revolving credit product (e.g., term loan). This amount can be requested via a single draw or via multiple draws. | Required if type = credit, structure = non_revolving, and the balance was created via an API workflow | number currency decimals |
| term_value | The number of units in the contractual term length for this non-revolving credit product (e.g., term loan). E.g., if the term length for the term loan is 6 months, this value should be set to 6. | Required if type = credit, structure = non_revolving, and the balance was created via an API workflow | integer, >0 |
| term_unit | The unit of the contractual term length for this non-revolving credit product (e.g., term loan). E.g., if the term length for the term loan is 6 months, this value should be months. Possible enums: days, weeks, months, years. | Required if type = credit, structure = non_revolving, and the balance was created via an API workflow | enum |
Deposit Details
(if applicable)| Field | Description | Required | Data Type |
|---|---|---|---|
| overdraft_limit | The overdraft amount offered to customers. | number currency decimals | Required for products with overdraft |
| federal_withholdings | The funds withheld due to federal requirements. | number currency decimals | Required for products with overdraft |
| state_withholdings | The funds withheld due to state requirements. | number currency decimals | Required for products with overdraft |
| nra_withholdings | The funds withheld due to NRA requirements. | number currency decimals | Required for products with overdraft |
Other
| Field | Description | Required | Data Type |
|---|---|---|---|
| metadata | Additional metadata associated with the balance that needs to be provided. E.g., in a lending case we may request that both standard APRs and promo APRs be included for additional Lead oversight. JSON strings embedded in CSV fields must be enclosed in double quotes, with internal double quotes escaped by doubling them (""). | Optional | JSON |
| generated_at | The timestamp when this file was generated. This should always be the date the file is sent to Lead Bank. | Required | datetime ISO8601 |
| effective_at | The timestamp when the related object(s) were polled to collect the information for this record. This is typically an EOD timestamp on one day prior to the generated_at timestamp, since T-1 EOD balances (effective_at) are reported on T (generated_at). | Required | datetime ISO8601 |