Creating an application

Your backend creates the application server-to-server with a bearer token, regardless of whether a browser will be involved later. The response is the application as stored, plus a plaintext client secret you can hand to a browser if you need one. POST /embedded-banking/v1/bank-account-applications

Create Request

curl -X POST 'https://api.sandbox.tesouro.com/embedded-banking/v1/bank-account-applications' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "applicant": { ... },
    "businessDetails": { ... },
    "businessOwners": [ ... ]
  }'

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "applicant": { ... },
  "businessDetails": { ... },
  "businessOwners": [ ... ],
  "clientSecret": "cs_..."
}

clientSecret is returned on every create response, but you only need it if a browser is going to finish the application. If your backend is going to drive the entire flow with its bearer token — the server-to-server integration shape — ignore the field and keep calling per-application endpoints with Authorization: Bearer. The secret carries no extra capability the bearer doesn’t already have. When a browser does need it: hand it directly to that browser context once, and do not log or persist it server-side. A later GET on the application does not return it. Token shape and header rules are covered in Application client secret. The exception is the onboarding component, which is not a browser surface you control and needs nothing passed to it. It looks the application up itself and gets its own copy of the secret. See Pre-populating an application. Pre-filling fields is optional — you can also create an empty application and PATCH everything in afterward, whether the PATCH calls come from your backend or a browser. If you are pre-filling so the applicant sees their details already entered in the onboarding component, Pre-populating an application covers what has to line up for the component to find what you created.

Acting on behalf of a child organization

Platform-level callers (a bank, ISO, platform partner, or fintech partner) can create an application for a specific child organization in their hierarchy by setting the X-Organization-ID header on the create request:

Targeting a child org

curl -X POST 'https://api.sandbox.tesouro.com/embedded-banking/v1/bank-account-applications' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'X-Organization-ID: 0a8c3f4d-1b2e-4d7a-9c5b-2e8f6a1d3c4b' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

The header is optional. If omitted, the application is created against the authenticated caller’s own organization, which is the right behavior for a platform partner creating an application for one of its own business customers. Set it when a platform credential needs to operate within a specific descendant org — for example, when Northfield Software’s parent bank uses its own credentials to create an application for a Northfield-owned sub-organization. The header is rejected if the target organization is not the caller’s own or a descendant of it. X-Organization-ID is accepted only on this endpoint. After creation, the application is addressed by its id and the organization is fixed.

Getting started

Authentication

Organizations

Users

Bank account applications

Bank accounts

Webhooks

Money movement

Transactions

White-label

Creating an application

Acting on behalf of a child organization

​Acting on behalf of a child organization

Acting on behalf of a child organization