Skip to main content
An account number is a routable payment address. It has a routing number and an account number. Counterparties use them to send you money over ACH, wires, and instant payments. You name the account number by ID when you send money out. You create account numbers for your customers and for your own program accounts. You manage their status and payment controls with the Account Numbers API. An account number doesn’t hold money. It references a balance, and every payment on the account number posts to that balance. You name the balance when you create the account number, and the account number returns it as balance. The balance is either a core balance on one of your program’s direct core accounts, or a user deposit balance beneath one of your customers’ user accounts. An account number also records who it belongs to. Every account number names an entity_id, and that entity is bound at creation.

​
Which balance an account number can point at

The table lists each kind of balance and whether an account number can point at it.

​
Who holds an account number

Every account number belongs to one entity, and that entity must already exist. Lead checks that it’s eligible for one of three roles, account_holder, minor_account_holder, or authorized_user. The entity also needs to already be an account holder or an allowed actor on the account behind the balance. Eligibility comes from the entity’s own data, and minor_account_holder only applies on programs Lead has approved for minor account holders. See Entity Eligibility. The role you pick also sets the account number’s default payment controls. An account_holder starts out accepting everything. A minor_account_holder or authorized_user starts with the restricted outgoing set described on Payment controls. An entity of type lead can’t hold an account number you create. There is no unassigned state and no assignment step. If an account number was created for the wrong entity, cancel it and create a new one.

​
How account numbers relate to the rest of the model

An account number connects to these objects:
  • Core balance. An account number on a direct core account makes that balance routable. Read the balance with the Core Balances API.
  • User deposit balance. An account number on a user deposit balance is how a customer receives and sends money. Lead settles each payment to the core balance behind the user deposit balance.
  • Entity. The entity_id on the account number is the customer or company the account number belongs to. See Entity.
  • Payments. ACH, wires, instant payments, and internal transfers reference an account number by account_number_id. Lead resolves the balance behind it, and each payment object returns the core balance it posted to as core_balance_id.
  • Originators. An account number that sends ACH under a specific originator sets ach_controls.originator_id. The originator’s core_balance_id must match the account number’s balance. See Originators.

​
What you can do

You can use these endpoints:
  • POST /v2/account_numbers: Create an account number on a balance for an entity. Lead generates the number.
  • POST /v2/account_numbers/register: Register a number you generated, on a balance for an entity.
  • GET /v2/account_numbers/{account_number_id}: Retrieve an account number.
  • GET /v2/account_numbers: List account numbers filtered by balance_id, entity_id, or account_number.
  • PATCH /v2/account_numbers/{account_number_id}: Update payment controls or metadata.
  • POST /v2/account_numbers/{account_number_id}/activate: Return an inactive account number to active.
  • POST /v2/account_numbers/{account_number_id}/deactivate: Move an active account number to inactive.
  • POST /v2/account_numbers/{account_number_id}/cancel: Permanently cancel an account number.
POST /v2/account_numbers and POST /v2/account_numbers/register require an Idempotency-Key header. The activate, deactivate, and cancel endpoints take no request body but require an Idempotency-Key. Calling one of them on an account number already in the target status returns the current object. See Idempotency.

​
Authentication

The endpoints use these scopes:
  • account_number/read_write for create, register, update, and status changes. Also grants read access.
  • account_number/read for the GET endpoints only.

​
What you can’t do

These actions aren’t available:
  • Create an account number without a balance and an entity. Both are required on every create and register request.
  • Create an account number on an FBO, a shadow account, a credit balance, or a balance Lead holds. The request returns 422.
  • Reassign an account number to another entity. There is no assign endpoint. Cancel it and create a new one.
  • Reactivate a canceled account number. The request returns an error. See Account Number Statuses.
  • Originate payments from an account number Lead holds. They appear on GET, and every rail returns an error when you name one as the sender.
  • Remove an entity from its account while it holds an account number that is active or inactive. Cancel the account number first.
  • Reference an account_id. It isn’t accepted on requests, returned on responses, or available as a filter.

​
In this section

These are the pages in this section: