Collateral File Schema - Lead | API Docs

File-era companion schema. This file accompanies the legacy file-based workflows above and remains the active path for programs that use it — it has no API successor yet.

The Collaterals object contains information about the relationship between a collateral asset and the secured account (e.g., a secured card account) it supports. Lead uses this information to ensure visibility into how secured products are collateralized.

Collateral files are only required when there are new collaterals to create or existing collaterals to update. On days with no new collaterals or updates, you must still submit a file containing only the header row. Partners must submit a collateral update whenever any field changes (e.g., a change in value_usd).

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

IDs

Field	Description	Required	Data Type
client_collateral_id	A unique identifier for the collateral object. This ID represents the relationship between the collateral asset and the credit product it secures — not the underlying asset itself. A single asset can secure multiple credit products (e.g., a single home securing both a mortgage and a HELOC); in this case, a unique `client_collateral_id` must be created for each asset-to-credit-product relationship.	Required	string
account_id	The ID of the account holding the credit balance this collateral secures. Must exist and must not be in a `closed` status at creation.	Required	string
balance_id	The ID of the deposit balance pledged as collateral. The Balance must be of `type` deposit, must belong to the same `account_id`, must not be in a `closed` status at creation, and at most one active collateral may exist per `balance_id`.	Required if `type` = `deposit_balance`	string

Details

Field	Description	Required	Data Type
type	The type of asset securing the credit product. Immutable after creation. `deposit_balance`: Fiat currency held at a financial institution. `real_estate`: Any permanent structure or fixture attached to land that cannot be moved without causing damage (e.g., single-family homes, apartments, commercial buildings).	Required	enum `deposit_balance` `real_estate`
value_usd	The value of the collateral in USD. Must be >= 0 with exactly 2 decimal places. When `type` = `deposit_balance`, the collateral value is captured via `balance.amount` in the Balance Object.	Required if `balance_id` is not present; must be empty if `balance_id` is present	number decimal (M,2)
status	The current status of the collateral. `active`: The collateral object and the asset it represents are actively being used to secure the credit product. `closed`: The collateral is no longer being used to secure the credit product, typically due to account or balance closure.	Required	enum `active` `closed`

Address

Address fields apply only to collateral of type real_estate.

Field	Description	Required	Data Type
address_line_1	Address line 1 of the real property.	Required if `type` = `real_estate`	string
address_line_2	Address line 2 of the real property.	Optional; must be empty if `type` != `real_estate`	string
address_city	City of the real property.	Required if `type` = `real_estate`	string
address_postal_code	Postal code of the real property (US format).	Required if `type` = `real_estate` and `address_country` = `us`	string
address_state	US state or territory (2-letter code).	Required if `type` = `real_estate` and `address_country` = `us`	string
address_country	ISO 3166-1 alpha-2 country code.	Required if `type` = `real_estate`	string

Other

Field	Description	Required	Data Type
generated_at	The day this file is generated. This should always be the date the file is sent to Lead Bank.	Required	datetime ISO8601
effective_at	The timestamp of when the related object(s) were polled to collect the information for this record. Must be T-1 of the file date.	Required	datetime ISO8601

Requirements for `type` = `deposit_balance`

The balance_id must reference a deposit balance that belongs to the same account_id specified in this record.
The deposit balance referenced by balance_id must contain only funds designated as collateral. Any funds that are not serving as collateral must not be held in this balance and should be reported under a separate deposit balance.

⌘I