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. The plaintext is not recoverable from a later GET; the service stores only a hash. Token shape, header, and PII-masking rules are covered in Application client secret. 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.

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

Embedded components

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