User Accounts: What You Open for Each Customer

A user account is what you open at Lead for each of your customers. It records who holds the user account, what it is used for, and the compliance data Lead needs to oversee it. You create user accounts, update them, and manage their status through the User Accounts API. A user account does not hold money itself. User credit balances and user deposit balances are separate resources that sit beneath it and reference its user_account_id. The bank accounts your program runs on, such as your FBO and operating accounts, are core accounts and are documented under Core Account. The creation of a user account for your end-user first happens in your system, and the user account record is how you communicate the terms of the product offered to your end-user to Lead. See Executing vs. Reporting.

​

Features

Every user account has one or more features that tell Lead how the user account is going to be used: deposit, credit_with_underwriting, or credit_without_underwriting. You ask for them in requested_features when you create the user account, and the user account returns them as features.

• If you intend to create User Deposit Balances under the user account, the deposit feature must be requested.
• If you intend to create User Credit Balances under the user account and your product has an explicit underwriting process where the end-user can be rejected (e.g., a business loan, a personal credit card), then request credit_with_underwriting.
• If you intend to create User Credit Balances under the user account and your product does not have an explicit underwriting process where the end-user can be rejected (e.g., courtesy overdraft), then request credit_without_underwriting.

Features set which fields are required and which compliance checks Lead runs. They also set which user credit balances and user deposit balances you can create under the user account. You can add features later, but you cannot remove them. The User Account Object page explains what each feature requires.

​

Product config and balance sheet model

Two fields are new on the user account:

• product_config_id is required on every create request. It identifies the product configuration your Lead team set up for your program. Your Technical Account Manager gives you the ID. You cannot change it after creation.
• balance_sheet_model is required when the user account has a credit feature: held_for_investment or held_for_sale. Lead checks it against the models your program allows. It is null on deposit-only user accounts.

​

Who holds a user account

Each user account lists its account holders, authorized signers, and authorized users by entity ID. Lead derives account_holder_type from the holders: consumer for individuals, commercial for businesses and sole proprietors. Commercial user accounts need at least one authorized signer. The User Account Object page documents more on this in the entities block.

​

Where it fits in onboarding

A user account can be created after its entities exist. For underwritten credit products, it can be created after the application is approved. Before your first POST request, get your product_config_id from your Technical Account Manager. Every POST request requires it. You cannot look it up through the API for now, but a Product Configuration API is planned. Here is the typical path you’ll follow:

​

How user accounts relate to the rest of the model

• Entities. Every person or business on the user account is an entity. Create entities first before attempting to create a user account.
• Applications. A user account with the credit_with_underwriting feature requires an approved application.
• User credit balances. User credit balances sit beneath the user account and reference a user_account_id.
• User deposit balances. User deposit balances sit beneath the user account and reference a user_account_id.
• Cards. Cards reference the user account by user_account_id.

​

What you can do

• POST /v2/user_accounts: Create a user account.
• GET /v2/user_accounts/{id}: Retrieve a user account.
• GET /v2/user_accounts?client_account_id={client_account_id}: Retrieve a user account by the client_account_id you assigned in an Account file. Use this to find the user_account_id for user accounts you created through Account files if you are moving to the API from files.
• PATCH /v2/user_accounts/{id}: Update a set of allowable fields.
• POST /v2/user_accounts/{id}/activate: Update the status of a user account to active.
• POST /v2/user_accounts/{id}/deactivate: Update the status of a user account to inactive.
• POST /v2/user_accounts/{id}/close: Close a user account.
• GET /v2/user_accounts/{id}/entity_relationships: List the entities linked to a user account and their relationship types.
• POST /v2/user_accounts/{id}/entity_relationships/batch: Add entities to a user account.
• DELETE /v2/user_accounts/{id}/entity_relationships/{entity_id}: Remove an entity from a user account.

​

Authentication

• user_account/read_write for create, update, status changes, and adding or removing entities. Also grants read access.
• user_account/read for the GET endpoints only. Use it when your integration only needs to read user accounts.

​

What you cannot do

• Mix old and new objects. User Accounts are designed to be adopted together with User Credit Balances, and with User Deposit Balances and Cards once they are available. Your Lead team will coordinate your move.
• Remove a feature. Features only grow. If a user account was opened with the wrong feature, close it and open a new one.
• Change product_config_id or balance_sheet_model. Both are set at creation. Lead may update balance_sheet_model if required by the terms of your program.
• Change status with PATCH. Use the activate, deactivate, and close endpoints. See User Account Statuses.
• Subscribe to User Account webhooks. There are no User Account webhook events. Your system sets every status, so read the User Account with GET when you need it.

​

In this section

• The User Account Object
• User Account Statuses