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 that maps to the id on the Account Object. Prior to creating a Balance record, an Account needs to exist with the right capabilities. | Required | string |
| client_balance_id | Client-generated unique ID of the balance. Populate this field only if the balance was initially created via a file workflow. If the balance was created via API, leave this field blank. Lead uses this ID to reconcile day-over-day changes to balance, and each balance has 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. Populate this field with the server-generated ID returned from a Create Subledger Balance API call. If the balance was not created via API, leave this field blank. Lead uses this ID to reconcile day-over-day changes to balance, and each balance has 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 validates that balance = outstanding_principal + outstanding_interest + outstanding_fees. | Required | number currency decimals |
| currency | The currency in which the balance is denoted. | Required | ISO4217 |
| 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. Do not include this amount in balance. For credit products, Lead validates 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. Do not include this amount in balance. For credit products, Lead validates 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, include the amount only in charge_off_balance, 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 | decimal(M, 6). E.g., 11.500000% interest rate reported as 11.500000. Previously, decimal(M, 3) was supported for credit products. |
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 must 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. | Required if the balance was created via an API workflow | enum: - revolving: Used for products where the available credit replenishes 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. |
| 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. Array of JSON objects — see field reference below. | 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 |
| 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 | The payment rail used to collect scheduled autopay repayments for this credit balance. Set to none if the borrower has not enrolled in autopay. Autopay is configured at the balance level — individual autopay repayments appear in the Transactions file as payment transactions whose transfer_type matches the rail used (e.g., ach, card). There is no separate autopay flag on the transaction record. | Required if type = credit | enum (ach, debit_card, wire, virtual_wallet, credit_card,none) |
| 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, set this value 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, set this value to months. Possible enums: days, weeks, months, years. | Required if type = credit, structure = non_revolving, and the balance was created via an API workflow | enum |
Repayment Details
Each object in therepayment_details array contains the following fields:
| Field | Description | Required | Data Type |
|---|---|---|---|
| expected_payment_frequency | The cadence at which the borrower is expected to make payments. | Required | enum: - business_daily: Once per business day- weekly: Once per week- biweekly: Once every two weeks (26 payments/year)- semi_monthly: Twice per month on fixed calendar days (24 payments/year)- monthly: Once per calendar month- quarterly: Once every calendar quarter (4 payments/year)- semi_annually: Once every 6 months (2 payments/year)- annually: Once per calendar year- fixed_interval: Payments occur after a fixed number of elapsed days; pair with expected_payment_frequency_interval_days- maturity: A single payment at loan maturity- variable: Repayment does not follow a predictable time-based cadence (e.g., event-driven repayment) |
| expected_payment_frequency_interval_days | The number of days between expected payments when the schedule follows a fixed interval rather than a calendar period. | Required when expected_payment_frequency = fixed_interval. Must not be present otherwise. | integer (1–730) |
| expected_number_of_payments | Expected total number of payments if the customer pays according to the loan schedule. | Optional | integer |
| expected_first_payment_date | Expected date of the first repayment. Also use this field for products with a single repayment. | Optional | date YYYY-MM-DD |
| expected_first_payment_amount | Expected amount of the first repayment. Also use this field for products with a single repayment. | Optional | currency decimals |
| expected_last_payment_date | Expected date of the final repayment. | Optional | date YYYY-MM-DD |
| expected_last_payment_amount | Expected amount of the final repayment. | Optional | currency decimals |
| expected_payment_amount | Anticipated amount for each repayment installment. | Optional | currency decimals |
JSON strings embedded in CSV fields must be enclosed in double quotes, with internal double quotes escaped by doubling them ("").Example value:
"{""repayment_details"":[{""expected_payment_frequency"":""monthly"",""expected_number_of_payments"":12,""expected_payment_amount"":""1000.00""}]}"Deposit Details
(if applicable)| Field | Description | Required | Data Type |
|---|---|---|---|
| overdraft_limit | The overdraft amount offered to customers. | Required for products with overdraft | number currency decimals |
| federal_withholdings | The funds withheld due to federal requirements. | Required for products with overdraft | number currency decimals |
| state_withholdings | The funds withheld due to state requirements. | Required for products with overdraft | number currency decimals |
| nra_withholdings | The funds withheld due to NRA requirements. | Required for products with overdraft | number currency decimals |
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 |