Skip to main content
Lead represents programs with a small vocabulary of objects: Entity, Application, Account, Account Number, Balance, and Transaction — plus two that apply only to customer products. The same names show up across the API, file schemas, webhook events, and reports, so learning them up front makes the rest of the documentation read more naturally. This is one of the first pages to read carefully if you’re new to Lead. The single most important idea is that these objects live on one of two surfaces — core and user — and the two work quite differently today. Rather than define each object once and qualify it per surface, this page walks through each surface on its own. Most of it is about how things work today; a short section at the end flags what’s changing.

​
Two Surfaces

Most objects sit on one of two surfaces, and the cleanest way to hold the distinction is:
  • Core Surface: The accounts you use to operate your program. Lead opens these during onboarding and manages their lifecycle; you read them but don’t open or close them yourself.
  • User Surface: The financial products your customers hold. You create these, manage their lifecycle, and report activity against them.
Your user accounts are the per-customer view, and your core accounts are where the money actually sits. Most programs use both, and the rest of this page explains them one at a time.

​
Entity (shared)

A legal person or organization — every account on either surface is held by one. You create entities for your customers with the Entity API (three subtypes: individual business, and sole_prop), and Lead creates an entity in your name for your program. The Entity is where Lead anchors KYC, OFAC screening, RFI handling, and any client-supplied risk score.
  • Identifier: entity_<id>, returned on creation. You can also reference an Entity by your own client_customer_id.
  • Roles: An Entity holds an Account in one or more roles — account_holder, authorized_signer, or authorized_user — which govern what it can do on the Account.
  • Lifecycle: Created and updated; some updates re-trigger KYC. Entities stay attached to any Account for the life of the relationship and can’t be deleted.

​
Core Surface

The foundational accounts you use to operate your program. Lead opens them for you during onboarding and manages their lifecycle; you read them through the online banking UI and the daily reports (API access Coming Soon), but you don’t open or close them yourself. They come in three kinds:
  • FBOs: Pooled “For Benefit Of” accounts that hold your customers’ funds in aggregate.
  • Operating Accounts: Our day-to-day DDAs for operating, revenue, reserve, settlement, network settlement, and so on.
  • Shadow Accounts: Secondary sweep or placement accounts, such as IntraFi ICS.

​
Account (core)

On the core surface, an Account and its balance are the same object — there is no separate core Balance. A core Account is one of your FBOs, operating DDAs, or shadow accounts, and it carries the balance. You read the balance from the Daily Balance Report or the online banking UI.
  • Identifier: account_<id>
  • Held by: Your Lead or partner entity
  • Lifecycle: Opened and managed by Lead

​
Account Number

The routing number and account number pair that lets money reach an account on Lead’s payment rails. A single core account can have many — for example, one for each end customer whose funds are pooled in an FBO. Account Numbers hang off core accounts. Even when you assign one to an individual customer, it attaches to the core account — the customer is carried on the account number’s entity_id — so an inbound payment lands on the core account first and is attributed to the customer from there.
  • Today: An Account Number points to a core Account (via account_id).
  • Lifecycle: Unassigned → active ↔ inactive → canceled. canceled is terminal; Account Numbers are never reused. See Account Number Statuses.
  • Controls: Per-rail allow/block rules for incoming and outgoing payments are set at the Account Number level. See Controls.
All of Lead’s money-movement APIs — ACH, wires, instant payments, and internal transfers — are indexed off the Account Number. You originate a payment by referencing an account_number_id, and Lead resolves the account it settles against.

​
Transaction (core)

Debits and credits on a core account are generated by Lead — you don’t report them. They appear in the Daily Activity Report and the online banking UI.

​
Core Accounts (today)

Entity (Lead or partner)
└── Account                   (account + balance combined)
    └── Account Number        (routable payment address)

​
User Surface

The financial products your customers hold — deposit and credit. You create them (via API or file), manage their lifecycle, and report their activity to Lead. Two of the objects here, Application and Card, exist only on the user surface — there is no core-side equivalent. The objects below appear roughly in the order you’d use them.

​
Application

For credit and lending products only (not deposit products). When your underwriting reaches a final decision, you submit it to the Applications API — approved, declined, or canceled — which Lead uses to meet Reg B and fair-lending obligations. An approved Application is required to open a credit or lending Account, so the order is Entity → Application → Account.
  • Identifier: application_<id>
  • Status: Terminal only — approved, declined, or canceled. There is no in-progress state, and all outcomes must be reported.

​
Account

A lightweight container for a customer’s product. It holds the entity relationships and sets the product type — deposit or credit — while the money itself lives on a Balance beneath it.
  • Identifier: account_<id>
  • Lifecycle: inactive ↔ active → closed (closed is terminal)
  • Holders: An Account can be held by more than one Entity — joint accounts, or business accounts with several signers.

​
Balance

How much money is on a user account at a point in time — its own object on the user surface. Two types:
  • Deposit: Checking or savings style accounts, with or without debit cards.
  • Credit: Term loans or lines of credit.
You report end-of-day balances to Lead for reconciliation.

​
Card

A card issued on a customer account — a debit card on a deposit account, or the card itself for a credit or charge product. You report cards to Lead in the card file, each tied to an account and entity and keyed by your own client_card_id.
  • Type: Virtual or physical; consumer, commercial, hsa, or fsa
  • Status: active, inactive, closed, or expired (closed is terminal)
  • Card transactions reference the Card

​
Transaction

A debit or credit posted to a user Balance, which you report to Lead via a daily batch file, keyed by your own client_transaction_id (API access Coming Soon)
  • Type: Indicates how the money moved — see Transaction Types for the full enumeration.
  • Posted vs. non-posted: Non-posted (pending) Transactions may not affect available balance the same way posted ones do; posted Transactions are final on the ledger.

​
User Accounts (today)

Entity (individual / business / sole_prop)

└── Account             (for credit, opened from an approved Application)

    ├── Card            (if the product issues cards)

    └── Balance         (deposit or credit)

        └── Transaction

​
How the Two Surfaces Connect

A single product ties both surfaces together. Take a checking product: each end customer is an Entity, and you open a user Account for them that carries a Balance. Their money physically pools in your FBO — a core Account Lead set up for you. You give the customer an Account Number for inbound ACH; today that number hangs off the core FBO even though it’s assigned to the customer. Each payment or fee posts as a Transaction on the user Balance, you report that activity to Lead, and Lead reflects the matching money movement on the FBO.
Key TakeawayToday, every Account Number hangs off the core Account — even the ones you assign to individual customers. That Account Number → Account linkage is the single most important thing to know about today’s model, and it’s the main thing changing.

​
What’s Changing

Today the two surfaces look different enough that this page treats them separately. The changes below bring them into a single, consistent shape. Lead is streamlining the model and exposing it through cleaner, purpose-built APIs over late 2026 and into 2027. The existing APIs and files keep working, and migration happens in cohorts with advance notice — you don’t need to do anything today. But three changes are worth keeping in mind so your integration adapts easily:
  • Balance and Transaction become first-class API objects on the core surface too. You’ll be able to read a core balance or transaction directly from the API instead of only from the daily reports.
  • Account Numbers will point to a Balance, not an Account. Instead of hanging off the core account, a customer’s Account Number will attach to that customer’s balance directly; an Account Number assigned to you or to Lead will attach to a core balance.
  • IDs gain typed prefixes. The single account_id used across both surfaces today is being replaced by typed IDs core_account_*, user_account_*, and so on) so the prefix tells you the object’s surface. Treat IDs as opaque strings; don’t parse meaning out of them.
The end state is a more consistent shape across both surfaces: Core Surface 
Entity

└── Core Account

    └── Core Balance            (deposit)

        ├── Core Transaction

        └── Account Number      (routable payment address)
User Surface 
Entity

└── User Account               (for credit, opened from an approved Application)

    ├── Card                   (if the product issues cards)

    └── User Balance           (deposit or credit)

        ├── User Transaction

        └── Account Number     (routable payment address)