> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# Balances Schema

> Field-by-field reference for the daily Balances file, including credit and deposit balances, rewards, repayment details, and autopay configuration.

<Check>
  For all optional fields where you do not plan to pass through data, please include the header and an empty value.
</Check>

Balances can be type `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](https://docs.lead.bank/api-integrations/accounts/overview#account-object). Prior to creating a Balance record, an Account needs to exist with the right [capabilities](https://docs.lead.bank/api-integrations/accounts/validations#capability-driven-validations).                                                                                        | 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](https://docs.lead.bank/api-reference/endpoint/subledger-balance/create-a-subledger-balance) 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<br />[ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) |
| status         | See [Balance Statuses](/file-integrations/balances-and-transactions/balance-statuses) for more detail. | Required     | enum                                                                            |
| status\_reason | See [Balance Statuses](/file-integrations/balances-and-transactions/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<br />[currency decimals](/file-integrations/file-delivery/currencies) |
| currency               | The currency in which the `balance` is denoted.                                                                                                                                                       | Required                                          | [ISO4217](https://www.iso.org/iso-4217-currency-codes.html)                  |
| 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<br />[currency decimals](/file-integrations/file-delivery/currencies) |
| outstanding\_interest  | The outstanding balance allocated to interest.                                                                                                                                                        | Required if `type` = `credit`                     | number<br />[currency decimals](/file-integrations/file-delivery/currencies) |
| outstanding\_fees      | The outstanding balance allocated to fees.                                                                                                                                                            | Required if `type` = `credit`                     | number<br />[currency decimals](/file-integrations/file-delivery/currencies) |

## Rewards Balance

<Info>
  See [Rewards Balance example](https://docs.lead.bank/file-integrations/balances-and-transactions/balance-reconciliation#examples).
</Info>

| **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 | enum<br />`usd`<br />`points`      |

## Dispute Balance

<Info>
  See [Dispute Balance example](https://docs.lead.bank/file-integrations/balances-and-transactions/balance-reconciliation#examples).
</Info>

| **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](/file-integrations/file-delivery/currencies); amount should be 0 or positive |
| dispute\_principal | The dispute balance allocated to principal. This amount is cumulative.                                                                                                                                         | Required if `type` = `credit` | [currency decimals](/file-integrations/file-delivery/currencies); amount should be 0 or positive |
| dispute\_interest  | The dispute balance allocated to interest. This amount is cumulative.                                                                                                                                          | Required if `type` = `credit` | [currency decimals](/file-integrations/file-delivery/currencies); amount should be 0 or positive |
| dispute\_fees      | The dispute balance allocated to fees. This amount is cumulative.                                                                                                                                              | Required if `type` = `credit` | [currency decimals](/file-integrations/file-delivery/currencies); amount should be 0 or positive |

## Charge Off Balance

<Info>
  See [Charge Off Balance example](https://docs.lead.bank/file-integrations/balances-and-transactions/balance-reconciliation#examples).
</Info>

| **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](/file-integrations/file-delivery/currencies); 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](/file-integrations/file-delivery/currencies); 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](/file-integrations/file-delivery/currencies); 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](/file-integrations/file-delivery/currencies); amount should be 0 or positive |

## Past Due Balance

<Info>
  See [Past Due Balance example](https://docs.lead.bank/file-integrations/balances-and-transactions/balance-reconciliation#examples).
</Info>

| **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](/file-integrations/file-delivery/currencies); 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](/file-integrations/file-delivery/currencies); 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](/file-integrations/file-delivery/currencies); 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](/file-integrations/file-delivery/currencies); 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. <br /><br />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.<br /><br />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`.  <br /><br />*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](/file-integrations/file-delivery/currencies) (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:<br />- `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.<br />- `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](#repayment-details) below.                                                                                                                                                                                                                                                                                                     | Required if `expected_maturity_date` is present and the balance was created via a file workflow.<br /><br />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.<br /><br />Required if `type` = `credit`, `structure` = `non_revolving`, and the balance was created via an API workflow. | number <br />[currency decimals](/file-integrations/file-delivery/currencies)                                                                                                                                                                                                                                                                                                                                                                                           |
| 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 <br />[currency decimals](/file-integrations/file-delivery/currencies)                                                                                                                                                                                                                                                                                                                                                                                           |
| 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 the `repayment_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:<br />- `business_daily`: Once per business day<br />- `weekly`: Once per week<br />- `biweekly`: Once every two weeks (26 payments/year)<br />- `semi_monthly`: Twice per month on fixed calendar days (24 payments/year)<br />- `monthly`: Once per calendar month<br />- `quarterly`: Once every calendar quarter (4 payments/year)<br />- `semi_annually`: Once every 6 months (2 payments/year)<br />- `annually`: Once per calendar year<br />- `fixed_interval`: Payments occur after a fixed number of elapsed days; pair with `expected_payment_frequency_interval_days`<br />- `maturity`: A single payment at loan maturity<br />- `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](/file-integrations/file-delivery/currencies)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 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](/file-integrations/file-delivery/currencies)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| expected\_payment\_amount                    | Anticipated amount for each repayment installment.                                                                     | Optional                                                                                      | [currency decimals](/file-integrations/file-delivery/currencies)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

<Info>
  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""}]}"`
</Info>

## Deposit Details

(if applicable)

| **Field**             | **Description**                                 | **Required**                         | **Data Type**                                                                |
| :-------------------- | :---------------------------------------------- | :----------------------------------- | :--------------------------------------------------------------------------- |
| overdraft\_limit      | The overdraft amount offered to customers.      | Required for products with overdraft | number<br />[currency decimals](/file-integrations/file-delivery/currencies) |
| federal\_withholdings | The funds withheld due to federal requirements. | Required for products with overdraft | number<br />[currency decimals](/file-integrations/file-delivery/currencies) |
| state\_withholdings   | The funds withheld due to state requirements.   | Required for products with overdraft | number<br />[currency decimals](/file-integrations/file-delivery/currencies) |
| nra\_withholdings     | The funds withheld due to NRA requirements.     | Required for products with overdraft | number<br />[currency decimals](/file-integrations/file-delivery/currencies) |

## 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. <br /><br />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<br />[ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) |
| 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<br />[ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) |