Pre-populating an application

If you already hold an applicant’s business and personal details, you can create the bank account application from your backend before the applicant ever sees a form. When they open the onboarding component, it finds that application, carries on with it, and renders your values in the fields. The applicant confirms and corrects rather than typing everything from scratch. This is a third integration shape alongside the two on the overview. The difference from “server creates, browser finishes” is that you never hand a credential to the browser. The component is not your UI, so there is nothing to pass it to. It authenticates itself against the application it finds.

How the component finds it

On start-up the component asks the API which application belongs to the signed-in applicant, and gets back the application’s id and the client secret it already carries. Three things have to line up for that answer to name your application:

The same OAuth client. The application has to be created by the same client whose client_id and client_secret you put in the widget token. An application created by a sibling client is not visible to this session at all.
The same applicant email. applicant.workEmailAddress on the application has to equal the address the applicant signs in with, which the widget token carries as the email claim on its subject token. This is the join; see Matching the applicant.
Still in DRAFT. A secret is handed back only while the application is editable. Once it is SUBMITTED there is nothing for the applicant to fill in.

Nothing is minted. The component receives the same secret your create call received, so your copy keeps working and a refresh, a second tab, or a retry all land on the same application.

Walking the flow

Create the application with what you hold

Set X-Organization-Reference to the same opaque business identifier you put in the widget token’s organization_reference claim, and include applicant.workEmailAddress. Everything else is optional, so send the fields you have and leave the rest out.

Create Request

curl -X POST 'https://api.sandbox.tesouro.com/embedded-banking/v1/bank-account-applications' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'X-Organization-Reference: northfield-cust-4821' \
  -H 'Content-Type: application/json' \
  -d '{
    "applicant": {
      "workEmailAddress": "alex@maplestreetcoffee.com",
      "firstName": "Alex",
      "lastName": "Chen",
      "mobilePhoneNumber": "5553452343",
      "homeAddress": {
        "address1": "234 Main St",
        "city": "Phoenix",
        "state": "AZ",
        "postalCode": "85001",
        "countryCode": "USA"
      }
    },
    "businessDetails": {
      "legalName": "Maple Street Coffee LLC",
      "dbaName": "Maple Street Coffee",
      "businessStructureType": "LLC",
      "phoneNumber": "5553453434",
      "website": "https://www.maplestreetcoffee.com",
      "northAmericanIndustryClassificationSystemCode": "SNACK_AND_NONALCOHOLIC_BEVERAGE_BARS",
      "address": {
        "address1": "123 Main St",
        "city": "Phoenix",
        "state": "AZ",
        "postalCode": "85001",
        "countryCode": "USA"
      }
    }
  }'

X-Organization-Reference is what scopes the lookup to one of your business customers. Without it the API can still find the applicant’s own application by email, but it cannot tell that a colleague at the same business already has one in progress, which is the check that stops a second application being started.

Do nothing with the client secret

The create response carries clientSecret as always. On this flow you do not need it: the component gets its own copy when it looks the application up. Drop it. Do not log it, persist it, or forward it to the browser.Your backend can keep patching the application with its bearer token right up until the applicant opens the component, which is useful if details arrive from your own onboarding steps over several minutes.

Render the component as normal

There are no extra props and no application id to thread through. The component does the lookup itself from the widget token, so the same markup serves a pre-populated applicant and one starting from nothing.

<EmbeddedProvider
  userId={currentUser.id}
  userEmail={currentUser.email}
  widgetTokenRefreshUrl="/api/widget-token"
>
  <OnboardingWidget bankingDashboardHref="/banking/dashboard" />
</EmbeddedProvider>

The component holds off rendering until the lookup settles, so the applicant never sees an empty form fill itself in a frame later.

The applicant confirms, corrects and submits

From here the flow is the ordinary one: edits, verification, submission. See Editing and submitting.

Matching the applicant

The applicant’s work email is the only thing that ties a stored application to the person in front of the component. Get it wrong and the failure is quiet rather than loud. An application whose workEmailAddress does not match the signed-in applicant, but which shares an X-Organization-Reference with them, is reported as belonging to somebody else at that business. Since a business may hold only one bank account application, the component then hides onboarding entirely, so the applicant sees no form at all rather than a blank one. That is correct when a colleague really did start the application, and is exactly the wrong outcome when the mismatch is a typo or a stale address on your side. So: create the application with the same address the applicant signs in with, and if that address changes before they finish, patch applicant.workEmailAddress to the new one.

What the applicant sees

Everything you stored comes back in the form, and every value stays editable. Two fields behave differently, because a read never returns them in full:

SSN and tax ID come back as their last four digits only. The field renders empty next to those four digits, and leaving it empty keeps what you stored. The applicant retypes one only if they want to change it.
Disclosure acceptance is never carried over. The applicant ticks the agreement in their own session, whatever your create call sent.

Beneficial owners are replaced as a set rather than merged, so the list the applicant sees is exactly the list on the application. If they delete one, it is gone.

How this interacts with resume

The secret the component picks up is the application’s own, and it expires like any other. See Expiry and refresh. A pre-populated application nobody opens runs past that window, and once it has, the lookup reports the application without a secret and the component cannot carry on with it. Resuming is the fix, and it is the same call as always: your backend posts the applicant’s email, a fresh secret is generated, stored on the application, and emailed to them. Storing it is the part that matters here. The component’s next look-up finds a live secret and picks the application up exactly as it would have on day one. The emailed copy is for an applicant working in a browser you handed a secret to; on this flow nobody has to open it. So the two pages solve different problems despite the shared word. Resume re-issues a credential that ran out. This page is about an application the browser was never handed a credential for in the first place.

Not the same as pre-filling through props

The onboarding component also accepts pre-filled values as props, documented under Pre-filling onboarding data. That path seeds the form in the browser and nothing is stored until the applicant presses Next. Pick whichever fits where your data already lives:

	Pre-populated application	Props
Where the values start	Your backend, stored on the application before the applicant arrives	Your page, passed into the component at render
Stored if the applicant never finishes	Yes	No
Reaches the applicant on a different device	Yes	No
Your backend can keep editing it	Yes	No

The two combine. Where both supply a field, the stored application wins, because it is the version the server will actually submit.

The same flow will apply to credit card applications once those are public. The API for them is not available today, so there is nothing to integrate against yet.

Getting started

Authentication

Organizations

Users

Bank account applications

Bank accounts

Webhooks

Money movement

Transactions

Embedded components

White-label

Pre-populating an application

How the component finds it

Walking the flow

Matching the applicant

What the applicant sees

How this interacts with resume

Not the same as pre-filling through props

​How the component finds it

​Walking the flow

​Matching the applicant

​What the applicant sees

​How this interacts with resume

​Not the same as pre-filling through props

How the component finds it

Walking the flow

Matching the applicant

What the applicant sees

How this interacts with resume

Not the same as pre-filling through props