> ## 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.

# Launch a Deposit Program

> Open deposit accounts your customers hold at Lead, move their money, and report their ledger.

This guide walks through launching customer deposit accounts — checking-style products, wallets, or stored value — where your customers' money is held at Lead. It's the foundation flow for most programs: the same chain underlies debit card programs and most money-movement products.

## **How it works**

Each customer is an **Entity**; each product they hold is an **Account** with the deposit capability; you provision routable **Account Numbers** so money can reach them; money moves over any [payment rail](/core-concepts/platform/money-movement); and you report **Balances and Transactions** daily as the ledger of record. Two account concepts are in play and must not be confused: the customer's *user* Account (the product container you create) and your program's *core* FBO (the Lead-managed pooled account where the money physically sits). **Account Numbers hang off the core account** — even when assigned to an individual customer, the number attaches to the FBO and carries the customer on its entity\_id; an inbound payment lands on the FBO and is attributed to the customer from there ([Object Model](/core-concepts/platform/object-model)).

## **Example scenario**

Nest Egg is a savings app. When Priya signs up, Nest Egg screens her, creates her Entity, opens her deposit Account, and provisions an account number against its program FBO with Priya's `entity_id` — the address she gives her employer for direct deposit. Her paycheck lands on the FBO and attributes to her via the account number; Nest Egg's ledger credits her, and its daily files report her balance and activity to Lead.

## **Objects involved**

| **Object**            | **Surface** | **Role in this flow**                                                     | **Reference**                                                                                                                                         |
| :-------------------- | :---------- | :------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entity                | user        | Priya, with your KYC/OFAC results attested                                | [Entity](/api-reference/endpoint/entity/create-an-entity)                                                                                             |
| Account               | user        | Priya's deposit product (capability: deposit)                             | [Accounts](/api-reference/endpoint/account/create-an-account)                                                                                         |
| Program FBO           | core        | The Lead-managed pooled account customer funds sit in                     | [Banking Infrastructure](/products/banking-infrastructure/overview)                                                                                   |
| Account Number        | core        | Routable address attached to the FBO, attributed to Priya via `entity_id` | [Account Numbers](/api-reference/endpoint/account-number/create-an-account-number)                                                                    |
| Balance / Transaction | user        | Your daily report of Priya's position and activity                        | [Balances](/file-reference/balances-and-transactions/balances-schema) & [Transactions](/file-reference/balances-and-transactions/transactions-schema) |
| ach\_payment (etc.)   | execution   | Money movement in and out                                                 | [Payment Rails](/core-concepts/platform/money-movement)                                                                                               |

## **Before you start**

* Sandbox credentials with entity, account, account-number, and rail scopes. Your program's FBO exists from onboarding — note its `account_id`; Step 3 needs it.
* **Balance and Transaction reporting is file-based today.** Daily files over SFTP, due by 6:00 a.m. CT the business day after the activity (empty file on quiet days) — [Balances](/file-reference/balances-and-transactions/balances-schema) & [Transactions](/file-reference/balances-and-transactions/transactions-schema), [SFTP setup](/file-reference/sftp-setup). User transaction and balance APIs are planned successors ([Platform Evolution](/core-concepts/platform/platform-evolution)).
* The Accounts API has a planned unified-model successor (the user account API), and Account Numbers will attach to balances rather than accounts under the unified model — same flows, typed IDs, migration in cohorts with notice ([Platform Evolution](/core-concepts/platform/platform-evolution)). Treat all IDs as opaque strings.

## **Integration steps**

### **Step 1: Create the customer Entity**

`POST /v0/entities`

`{ "type": "individual", "screening": { "...": "your KYC/OFAC results" }, "...": "..." }`

Keep Entity data current after launch — updates to identifying fields trigger re-screening attestations.

### **Step 2: Open the deposit Account**

`POST /v0/accounts`

`{ "entity_id": "...", "capabilities": ["deposit"] }`

Created active; account\_holder\_type derives from the entity types (all-individual → consumer). This user Account is the product container — it is *not* the account that Account Numbers attach to.

### **Step 3: Provision an Account Number — against the core account, not the user Account**

`POST /v1/account_number`

`{ "account_id": "your program FBO's core account_id", "entity_id": "Priya's entity_id", "...": "..." }`

<Note>
  ##### **The account\_id here is the core account's**
</Note>

Both the user Account (Step 2) and your core FBO have `account_<id>`-style identifiers, and passing the Step 2 id here is the most common wiring mistake in this flow. **Account Numbers attach to the core account** — your FBO — with the customer carried on `entity_id`; the user Account never appears in this call ([Object Model](/core-concepts/platform/object-model), "How the Two Surfaces Connect"). Then assign and activate per the [Account Number lifecycle](/products/account-number/account-number-object) — the number can't transact until active. *(Under the unified model, account numbers will point to a balance instead; the create call changes shape, the concept — a routable address attributed to a customer — doesn't.)*

**Decision point:** one number per customer is the common pattern; issue additional numbers when the product needs distinct addresses per purpose (e.g. a dedicated direct-deposit number), and use per-number [controls](/products/account-number/controls) to scope what each address accepts.

### **Step 4: Receive money**

`POST /v1/simulate/ach/incoming_ach`

`{ "account_number": "...", "amount": 50000, "...": "..." }`

The payment lands on the FBO; attribute it to Priya via the account number it arrived on. Handle `ach.posted` to credit her in your ledger. Verify webhook signatures and handle replays from the first handler you write ([webhooks](/api-integrations/using-the-api/webhooks)).

### **Step 5: Send money**

Send over the rails your program uses, wiring up each rail's webhooks and returns per its pages under [Payment Rails](/core-concepts/platform/money-movement). **Decision point:** rail choice is a product decision — [Money Movement](/core-concepts/platform/money-movement) compares reach, speed, finality, and operating hours.

### **Step 6: Report**

Produce your first Balance and Transaction files, submit over SFTP, and clear validation against the [File Reference](/file-reference/overview) schemas. Cadence and semantics: [Balances](/file-reference/balances-and-transactions/balances-schema) & [Transactions](/file-reference/balances-and-transactions/transactions-schema).

## **Handling exceptions**

| **What happens**                    | **Signal**                                              | **What to do**                                                                                                                                       |
| :---------------------------------- | :------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
| Incoming ACH returned               | Return per [ACH returns](/products/ach/exceptions)      | Debit your ledger; notify the customer. Certain consumer unauthorized returns can arrive weeks after posting — hold policies are a product decision. |
| NOC received                        | [ACH NOCs](/products/ach/statuses)                      | Update counterparty details before your next origination.                                                                                            |
| Payment held for review             | status under\_review                                    | Monitor; don't promise availability until posted.                                                                                                    |
| Inbound payment can't be attributed | Your reconciliation of the FBO                          | Check which account number it arrived on and its entity\_id; unattributable funds are an ops process to define before launch.                        |
| File fails validation               | [file delivery errors](/file-reference/delivery/errors) | Correct and resubmit before the deadline.                                                                                                            |

## **Testing this flow in sandbox**

The full chain runs in sandbox: attested-passed screening, account and account-number lifecycle, the incoming-ACH simulator with advance, and each contracted rail's simulators per [Environments & testing](/core-concepts/platform/environments-and-testing). Exercise at least one return path per rail and validate files against realistic volume before production submission.

## **Related**

[Object Model](/core-concepts/platform/object-model) (the two surfaces — read this if Step 3's warning surprised you) · [Balances](/file-reference/balances-and-transactions/balances-schema) & [Transactions](/file-reference/balances-and-transactions/transactions-schema) · [Account Numbers](/products/account-number/overview) · [Payment Rails](/core-concepts/platform/money-movement) · [Make Your First Payment API Call](/get-started/quickstart/make-your-first-payment-api-call) · [Launch a Debit Card Program](/guides/issue/debit-card-program) · [Reports Lead Delivers](/file-reference/reports/platform-reconciliation)

*If something in this guide doesn't match what you see, contact your Lead team.*