Skip to main content
Lead’s APIs follow two different contracts, and knowing which one you’re holding predicts almost everything about how an API behaves — whether it sends webhooks, whether a status is authoritative or declarative, and what happens when you make a mistake. This page explains the two contracts once, so the rest of the documentation doesn’t have to re-explain them product by product.

​
The two contracts

Execution APIs make something happen. When you call POST on a payment rail — ACH, Wires, Instant Payments, Internal Transfers, Blockchain Payments — or request a Funding, you are instructing Lead to move money. Lead is the actor: it validates the instruction, submits it to a payment network or its core ledger, and owns the outcome. The object’s status is authoritative — it tells you what has actually happened to real money, and only Lead’s systems change it. Reporting APIs tell Lead something that happened in your systems. For the products your customers hold, you are the ledger of record, not Lead. Your platform decided the underwriting outcome, opened the account, issued the card, posted the fee. Lead is your regulator-facing partner bank, and it needs an accurate, timely picture of that activity for compliance oversight — so you report it, through the Entity, Applications, Accounts, and Cards APIs, and through the daily Balance and Transaction files. Here the object’s status is declarative — it reflects what you told Lead is true in your ledger.

​
Why the distinction predicts API behavior

Webhooks exist where Lead knows something you don’t. Payment rails emit webhooks ach.posted, wire.rejected, instant_payment.counterparty_status_updated, funding.posted) because the state lives on Lead’s side and in the payment networks — Lead is telling you what happened. Reporting objects generally don’t emit webhooks for lifecycle changes, because you made the change; there is nothing Lead knows that you don’t. “Terminal” means different things. On an execution object, a terminal status describes reality: a returned ACH was returned; that cannot un-happen. On a reporting object, a terminal status describes your report — and reports can be wrong. This is why, for example, a Card reported as closed can be corrected back to active through the API: the correction isn’t reopening a card, it’s fixing an inaccurate report so Lead’s picture matches your ledger. If a rule on a reporting API looks strange, re-read it as “keep Lead’s copy accurate” and it usually makes sense. Mistakes have different blast radii. A duplicate execution call risks moving money twice — which is why every write endpoint requires an Idempotency-Key, and why you should treat idempotency on payment rails as non-negotiable. A duplicate or erroneous report corrupts Lead’s picture of your ledger — no money moves, but your compliance reporting is now wrong, and correcting it is on you. Timeliness obligations differ. Execution is on-demand: you call when you want money to move. Reporting is an obligation with a clock: Lead needs your customer activity on a defined cadence whether or not anything interesting happened.

​
Where each API sits

​
One more consequence: which numbers are “real”

Because you are the ledger of record for customer products, the balance Lead holds for a customer product is a reported figure, reconciled against actual money movement on the core accounts Lead operates (your FBO and operating accounts). When you’re debugging “where is the money,” the execution objects and the core-account reports are the ground truth of movement; the reporting objects are the ground truth of attribution. The Object Model page describes how the two surfaces connect.