Skip to main content
You manage account number status. Every new account number starts active, and you move it with the activate, deactivate, and cancel endpoints. Lead can also deactivate an account number under its own policies.

​
Lifecycle

The diagram shows every status and transition.

​
Statuses

The table lists each status.

​
Transitions

The table lists which endpoint makes each transition. The three endpoints take no request body but require an Idempotency-Key. Here’s what they do when the account number is already in that status, or can’t reach it:
  • Calling /deactivate on an inactive account number, or /cancel on a canceled one, returns 200 with the current object.
  • Calling /activate on a canceled account number returns an error. A canceled account number can’t be reused.
You can’t change status with PATCH.

​
What a status means for payments

Status affects payments as follows:
  • Incoming. Only an active account number receives. Lead returns or rejects payments addressed to an inactive or canceled account number on each rail’s normal path.
  • Outgoing. Only an active account number sends. Lead rejects a payment request that names an inactive or canceled account number.
  • Status doesn’t cascade. Changing the status of the core balance or user deposit balance behind an account number doesn’t change the account number’s status. Lead rejects payments on the balance instead.

​
Observing changes

You can learn about changes these ways:
  • account_number.created webhook. Sent when Lead creates an account number on your program. Account numbers you create return synchronously and don’t emit it.
  • No status webhooks. Activate, deactivate, and cancel return the updated object in the response. Webhooks & Events lists the matching events as not sent.
  • Polling. GET /v2/account_numbers/{account_number_id} returns the current status.