Create a customer account

curl --request POST \
  --url https://api.brale.xyz/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "business_name": "ABC Company Inc",
  "ein": "11-1111111",
  "address": {
    "street_line_1": "100 Example St",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  },
  "phone_number": "2125550182",
  "email": "[email protected]",
  "website": "https://abc.example",
  "beneficial_owners": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "dob": "1980-05-12",
      "ssn": "222-22-2222",
      "email": "[email protected]",
      "phone_number": "212-555-0182",
      "address": {
        "street_line_1": "100 Example St",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US"
      }
    }
  ],
  "business_controller": {
    "first_name": "Alicia",
    "last_name": "Ng",
    "dob": "1986-07-14",
    "ssn": "123-45-6789",
    "email": "[email protected]",
    "phone_number": "+12125550182",
    "address": {
      "street_line_1": "200 Market St",
      "city": "New York",
      "state": "NY",
      "zip": "10002",
      "country": "US"
    }
  },
  "tos_attestation": {
    "accepted_at": "2025-05-13T20:45:15Z",
    "version": "2025-04-01",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ..."
  },
  "name": "My Account"
}
'

{
  "id": "2VcUIIsgARwVbEGlIYbhg6fGG57"
}

{
  "type": "unsupported_account_combination",
  "message": "The combination of entity_type, account_type, and verification_mode is not supported."
}

{
  "type": "unsupported_account_combination",
  "message": "The combination of entity_type, account_type, and verification_mode is not supported."
}

POST

accounts

curl --request POST \
  --url https://api.brale.xyz/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "business_name": "ABC Company Inc",
  "ein": "11-1111111",
  "address": {
    "street_line_1": "100 Example St",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  },
  "phone_number": "2125550182",
  "email": "[email protected]",
  "website": "https://abc.example",
  "beneficial_owners": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "dob": "1980-05-12",
      "ssn": "222-22-2222",
      "email": "[email protected]",
      "phone_number": "212-555-0182",
      "address": {
        "street_line_1": "100 Example St",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US"
      }
    }
  ],
  "business_controller": {
    "first_name": "Alicia",
    "last_name": "Ng",
    "dob": "1986-07-14",
    "ssn": "123-45-6789",
    "email": "[email protected]",
    "phone_number": "+12125550182",
    "address": {
      "street_line_1": "200 Market St",
      "city": "New York",
      "state": "NY",
      "zip": "10002",
      "country": "US"
    }
  },
  "tos_attestation": {
    "accepted_at": "2025-05-13T20:45:15Z",
    "version": "2025-04-01",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ..."
  },
  "name": "My Account"
}
'

{
  "id": "2VcUIIsgARwVbEGlIYbhg6fGG57"
}

{
  "type": "unsupported_account_combination",
  "message": "The combination of entity_type, account_type, and verification_mode is not supported."
}

{
  "type": "unsupported_account_combination",
  "message": "The combination of entity_type, account_type, and verification_mode is not supported."
}

Use the playground below to try this endpoint directly, or review the OpenAPI details in the right panel.

Verification documents: Stage KYB documents first, then either pass the returned doc_submission_ids on this request or link them afterward. If Brale’s review later requires more documents, subscribe to account.verification.documents_required (see Webhook Events) or poll required documents — stage and link those documents the same way. When verification passes, Brale sends account.verification.completed and the account status becomes complete.

Linking documents at creation

Include optional doc_submission_ids in the request body to link staged document submissions when the account is created. Each ID must come from a prior Stage a Verification Document call (POST /documents). Omit the field to create the account without documents and link them later.

Field	Type	Required	Description
`doc_submission_ids`	array of strings (KSUID)	No	Staged submission IDs to link and upload as part of account creation.

doc_submission_ids is not supported for testnet-only clients or self-attested accounts. In those cases, omit the field or link documents after creation if supported for your account type. For the full account creation payload (business details, controller, beneficial owners, TOS attestation), see Accounts. For the individual (KYC) path, see Accounts — Creating an individual account.

Choosing between a business and an individual account

POST /accounts accepts three optional dimension fields — entity_type, account_type, and verification_mode — that select between a KYB-verified business account with Brale-custodied wallets and a KYC-verified individual account without custody. Omitting all three preserves today’s business behavior. See Account types for the full matrix.

Example request with documents (business)

{
  "business_name": "Acme Corp",
  "ein": "12-3456789",
  "address": {
    "street_line_1": "123 Main St",
    "city": "Des Moines",
    "state": "IA",
    "zip": "12345"
  },
  "phone_number": "2134678902",
  "email": "[email protected]",
  "website": "https://acme.example.com",
  "business_controller": {
    "first_name": "John",
    "last_name": "Doe",
    "ssn": "222-22-2222",
    "dob": "1981-01-25",
    "email": "[email protected]",
    "phone_number": "2154688987",
    "ownership_percentage": "50",
    "address": {
      "street_line_1": "456 Elm St",
      "city": "Chicago",
      "state": "IL",
      "zip": "60601"
    }
  },
  "beneficial_owners": [],
  "tos_attestation": {
    "version": "2025-04-01",
    "accepted_at": "2026-06-09T10:00:00Z"
  },
  "doc_submission_ids": [
    "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
    "3Ar9BnQCKIrB3SYjKGBzCtFs6XM"
  ]
}

Example response (201)

{
  "id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
  "name": "Acme Corp",
  "status": "pending",
  "created": "2026-06-09T10:00:00Z",
  "updated": "2026-06-09T10:00:00Z"
}

Linked documents are uploaded asynchronously after the account is created. The account status remains pending while Brale reviews the submission.

Example request (individual)

Create a KYC-verified individual account. The individual object and tos_attestation are required. Business-only fields (business_name, ein, website, business_controller, beneficial_owners) must not be sent on this path.

{
  "entity_type": "individual",
  "account_type": "transactional",
  "verification_mode": "standard",
  "individual": {
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1990-01-01",
    "email": "[email protected]",
    "phone_number": "2125550182",
    "country": "US",
    "address": {
      "street_line_1": "123 Main St",
      "street_line_2": "Apt 4",
      "city": "New York",
      "state": "NY",
      "zip": "10001"
    },
    "identity": {
      "number": "222-22-2222",
      "type": "SSN9"
    }
  },
  "tos_attestation": {
    "version": "2025-04-01",
    "accepted_at": "2026-05-13T20:45:15Z",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 ..."
  }
}

Example response, individual (201)

{
  "id": "3Ar9BnQCKIrB3SYjKGBzCtFs6XL",
  "name": "Jane Doe",
  "status": "pending",
  "created": "2026-05-13T20:45:16Z",
  "updated": "2026-05-13T20:45:16Z"
}

The account’s name is derived from the individual’s first and last name. status transitions to complete when KYC succeeds and account.verification.completed fires. See Individual accounts for the end-to-end workflow, including the receive-only constraints on transactional accounts.

Required scope

accounts:write

Authorizations

Authorization

string

header

required

Use the Bearer token returned from the Auth endpoint via OAuth2 client_credentials flow. Include the token in the "Authorization: Bearer " header.

Headers

Idempotency-Key

string

required

A unique string used to prevent duplicate operations. Each POST request must use a new idempotency key. Use a UUIDv4 string. Example: idemp-123e4567-e89b-12d3-a456-426614174000

Body

application/json

CreateManagedAccountRequest
CreateIndividualAccountRequest

Business (KYB) account creation payload. This is the default path when entity_type is omitted, or when it is explicitly set to business with account_type: custodial and verification_mode: standard.

business_name

string

required

Example:

"My Customer"

ein

string

required

Example:

"123456789"

address

USStreetAddress · object

required

Show child attributes

business_controller

ControllingParty · object

required

Show child attributes

string

required

Example:

"[email protected]"

phone_number

string

required

Example:

"515-555-1212"

tos_attestation

EndUserTosAttestation · object

required

Show child attributes

website

string

required

Example:

"https://example.com"

entity_type

enum<string>

Optional discriminator. When omitted, defaults to business.

Available options:

business

Example:

"business"

account_type

enum<string>

Optional. When omitted, defaults to custodial for business accounts.

Available options:

custodial

Example:

"custodial"

verification_mode

enum<string>

Optional. When omitted, defaults to standard.

Available options:

standard

Example:

"standard"

beneficial_owners

ControllingParty · object[] | null

Show child attributes

ultimate_beneficial_owners

ControllingParty · object[]

deprecated

Deprecated alias of beneficial_owners.

Show child attributes

name

string

Example:

"My Account"

doc_submission_ids

string<ksuid>[]

Optional pre-staged verification document submission IDs to link on creation.

Pattern: ^[a-zA-Z0-9]{26}$

Response

Account successfully created

string<ksuid>

Pattern: ^[a-zA-Z0-9]{26}$

Example:

"2VcUIIsgARwVbEGlIYbhg6fGG57"

⌘I

API overview

Accounts

Addresses

Automations

Transfers

Financial institutions

Webhooks

Tokenization

Create a customer account

Linking documents at creation

Choosing between a business and an individual account

Example request with documents (business)

Example response (201)

Example request (individual)

Example response, individual (201)

Required scope

Authorizations

Headers

Body

Response

​Linking documents at creation

​Choosing between a business and an individual account

​Example request with documents (business)

​Example response (201)

​Example request (individual)

​Example response, individual (201)

​Required scope

Authorizations

Headers

Body

Response

Linking documents at creation

Choosing between a business and an individual account

Example request with documents (business)

Example response (201)

Example request (individual)

Example response, individual (201)

Required scope