Bank account applications

A bank account application is a first-class object in the Embedded Banking API. Your backend creates it, applicant and business details get filled in, the bank decisions it. Each application moves through a small set of states on its way to a decision, and which credential you use to act on it depends on whether a browser is involved.

What an application collects

An application collects information on three entities:

Business entity: Legal information about the business itself
Business controller: An individual with the power to direct or significantly influence the financial activities of the business (e.g. CEO, CFO, VP)
Beneficial owners: Any person who owns 25% or more of the company’s ownership interests

What KYB collects lists the details for each one.

Integration shapes

How you drive an application depends on whether a browser sits between you and the API.

Server-to-server only. Your backend holds a bearer token and drives the entire lifecycle — create, edit, verify, submit — from server code. The client secret is never issued. Pick this when you’ve already collected applicant and business details out of band, or when KYC/KYB happens outside Tesouro and the application is essentially a system-of-record entry for the bank.
Server creates, browser finishes. Your backend creates the application and receives a short-lived application client secret in the create response. You hand the secret to a browser surface, such as your own UI or the white-label hosted app, and the browser drives the rest without holding a backend bearer token. Pick this when end users need a UI.
Server pre-populates, the onboarding component finishes. Your backend creates the application with the details it already holds, and Tesouro’s onboarding component finds it and shows the applicant a form that is already filled in. You hand the browser nothing, because the component looks the application up itself. Pick this when the UI is Tesouro’s rather than yours. See Pre-populating an application.

The scoped client secret is a browser credential, not a server-side one. Backend integrators have no reason to issue one, and never need to think about the resume flow.

States

DRAFT

Editable. The applicant can update applicant, business, and beneficial-owner details and request the verification codes that precede submission.

SUBMITTED

Read-only. The applicant has called the submission endpoint; the bank’s KYC/KYB pipeline is running. Your backend can read the application but no one can edit it.

COMPLETE

Terminal. The bank has finished processing and the underlying bank account exists. The application is read-only and the client secret is invalidated.

Transitions never move backward: there’s no edit-after-submit and no return to DRAFT from a later state. Beyond the happy path above, an application can also land in one of three other terminal states:

State	From	How it happens
`DENIED`	`SUBMITTED`	The bank declines the application.
`CANCELED`	`SUBMITTED`	`DELETE /embedded-banking/v1/bank-account-applications/{id}` while the bank’s decision is pending.
`DELETED`	`DRAFT`	The same delete call, before submission.

Subscribe to BANK_ACCOUNT_APPLICATION_STATUS_CHANGED to react to any of these transitions, including COMPLETE.

Outcomes

Once the application is submitted, the bank’s decision is one of three outcomes:

Outcome	Description
Instant approval	The user can immediately access the banking dashboard and start using the account
Manual review	The bank requires additional review time; the user is notified via email when complete
Denied	The application is denied if it appears fraudulent or too risky for the bank

Onboarding outcomes covers what your product should do with each one.

Auth at each step

Per-application calls accept either a backend bearer token (from the client credentials flow) or the application client secret — whichever credential the caller actually has. Backend-only integrations use bearer for every row. Hybrid integrations use bearer to create and resume, and the browser uses the client secret for the per-application rows in the middle.

Step	State after	Auth options
Create application	`DRAFT`	Bearer
Read application	unchanged	Bearer or client secret
Edit applicant / business / owners	`DRAFT`	Bearer or client secret
Request a verification code	`DRAFT`	Bearer or client secret
Submit applicant verification	`DRAFT`	Bearer or client secret
Submit application	`SUBMITTED`	Bearer or client secret
Re-issue a client secret to resume	unchanged (`DRAFT`)	Bearer

The client secret accepts only those per-application rows — it cannot create a new application, resume another one, or reach non-application endpoints. It is invalidated when the application reaches COMPLETE. After that, the application is reachable only with a backend bearer token. See Application client secret for token shape and header.

Where to next

Creating an application

Create the application server-to-server, receive the client secret, and act on behalf of a child organization with X-Organization-ID.

Editing and submitting

Patch in remaining details, verify the applicant, and submit the application to the bank.

Resuming

Re-issue a client secret for a stale DRAFT application and deliver it to the applicant by email.

Pre-populating

Create the application with the details you already hold and let the onboarding component pick it up.

Getting started

Authentication

Organizations

Users