Accounts

Accounts are represented by account_id values, which are assigned to verified entities. If you have an API Key and Secret, your application has its own account_id. You can also create additional account_id values for your business clients or for individual end users. Three shapes are supported today:

Business, custodial (KYB) — the existing behavior. The account holds one or more Brale-custodied (type=internal) on-chain wallets, can originate transfers, and can hold off-chain bank Addresses.
Business, transactional (KYB) — a KYB-verified business that is non-custodial. It has no internal Brale wallet and no stored balance at Brale, and it registers external, self-custody destination addresses.
Individual, transactional (KYC) — a natural person verified with KYC. The account holds no custody at Brale, cannot originate on-chain transfers, and only receives value through external destination addresses. See Individual accounts.

Individual custodial accounts are not currently supported. Geographic eligibility for each shape depends on the account’s U.S. state — see Account availability for the canonical state table. Which shape you get is controlled by three optional dimension fields on POST /accounts. Omitting them all preserves today’s business/KYB behavior. See Account types for the full matrix. Each custodial account_id is associated with one or more custodial (type=internal) onchain wallets, which are represented by address_id values. Off-chain bank accounts are also represented as Addresses (using address_id). Transactional accounts (business or individual) have no internal addresses. The legacy financial_institution_id is deprecated — new integrations should use address_id and the Addresses resource instead. The account_id is used in the request URL across many Brale API endpoints to scope the request to a specific application or client. To KYB and approve a business account, we collect key details such as business name and EIN. To KYC an individual account, we collect the person’s legal name, date of birth, address, and government identifier. For more information, see our Compliance Requirements. If additional details are required, Brale will notify you with the steps to complete verification.

Business customers can also self onboard at https://app.brale.xyz/signup. Individual accounts are managed entirely through the API — there is no end-user dashboard for them.

Account dimensions

POST /accounts accepts three optional discriminator fields:

Field	Values	Default when omitted
`entity_type`	`business`, `individual`	`business`
`account_type`	`custodial`, `transactional`	`custodial`
`verification_mode`	`standard`, `reliance`	`standard`

Supported combinations:

`entity_type`	`account_type`	Status	Verification
`business`	`custodial`	Supported	KYB (existing behavior)
`business`	`transactional`	Supported	KYB
`individual`	`transactional`	Supported	KYC (`verification_mode` may be `standard` or `reliance`)
`individual`	`custodial`	Not currently supported	—

An unsupported combination is rejected with 422 unsupported_account_combination. The rejection is permanent, so it is safe for clients to cache the error against an idempotency key.

Omitting all three dimension fields produces exactly today’s behavior. Existing integrations that create business accounts do not need to change.

For a fuller discussion of when to choose each combination, see Account types. For where each combination is available, see Account availability.

Creating a business account

You are required to pass in business information, controller information, and ultimate beneficial owner information. POST https://api.brale.xyz/accounts

Request

{
  "business_name": "ABC Company Inc",
  "ein": "12-3456789",
  "address": {
    "street_line_1": "123 Main St",
    "street_line_2": "Apt C",
    "city": "Des Moines",
    "state": "IA",
    "zip": "50309"
  },
  "phone_number": "2134678902",
  "email": "[email protected]",
  "website": "abccompany.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",
      "street_line_2": "Suite 5", // Optional
      "city": "Chicago",
      "state": "IL",
      "zip": "60601"
    }
  },
  "beneficial_owners": [
    // Required for all individuals who own 25% or greater of the business
    {
      "first_name": "Bob",
      "last_name": "Nguyen",
      "ssn": "888-77-6666",
      "dob": "1981-11-02",
      "email": "[email protected]",
      "phone_number": "2675550456",
      "ownership_percentage": "50",
      "address": {
        "street_line_1": "301 Chestnut Street",
        "city": "Philadelphia",
        "state": "PA",
        "zip": "19106"
      }
    }
  ],
  "tos_attestation": {
    "version": "2025-04-01",
    "accepted_at": "2025-05-13 20:45:15Z",
    "ip": "203.0.113.42", // Optional
    "user_agent": "Mozilla/5.0 ..." // Optional
  }
}

Presenting the Brale End-User Agreement

Partners must show the exact Brale End-User Agreement (EUA) to their end users before calling POST /accounts and capture consent. The most recent version is hosted at https://brale.xyz/legal/end-user-agreement.

Business account — Required vs. Optional Fields

Field	Type	Required	Description
`business.name`	string	Yes	Registered legal name
`business.website`	string	Yes	Full URL incl. https://
`business.phone`	string	Yes	Accepts multiple common formats: digits only `8134688604`, dashed `813-468-8604`, or with country code `18134688604`. Area code must be valid.
`business.address.street_line_1`	string	Yes
`business.address.street_line_2`	string	No	Apt / Suite / Floor.
`business.address.city`	string	Yes
`business.address.state`	string	Yes	Abbreviated format (NY, FL)
`business.address.zip`	string	Yes
`business_controller`	object	Yes	One natural person who exercises control. Controllers outside the US are supported; see Non-US controllers and beneficial owners.
`beneficial_owners`	array	Yes	Individuals with ≥25% ownership. Owners outside the US are supported on the same terms as the controller.
`tos_attestation`	object	Yes

Non-US controllers and beneficial owners

A controller or beneficial owner outside the US is created through the same POST /accounts call. Only the fields that depend on where the person lives change:

Field	US party	Party outside the US
`address.country`	`US`, or omitted	ISO 3166-1 code or country name, e.g. `CO`
`address.state`	Required, must be a US state abbreviation	Optional and free-form; omit it for countries with no state or province
`address.zip`	`#####` or `#####-####`	Any format
`ssn`	Required, `###-##-####`	Not accepted
`identity`	Optional, for a document other than an SSN	Required: the number and the document type
`phone_number`	US number	Parsed against `address.country`, so a national-format number is accepted

ssn and identity are mutually exclusive and exactly one is required. Sending ssn for a party outside the US returns 400, because an SSN has no meaning there. Use the identity type that matches the document. The business itself is still US-only. This covers a US business whose controller or owners live elsewhere, not a foreign entity.

Request

{
  "business_name": "ABC Company Inc",
  "ein": "12-3456789",
  "address": {
    "street_line_1": "123 Main St",
    "city": "Des Moines",
    "state": "IA",
    "zip": "50309"
  },
  "phone_number": "2134678902",
  "email": "[email protected]",
  "website": "https://abccompany.com",
  "business_controller": {
    "first_name": "Ana",
    "last_name": "Gomez",
    "dob": "1985-01-15",
    "email": "[email protected]",
    "phone_number": "3001234567",
    "ownership_percentage": "40",
    "identity": {
      "number": "1020304050",
      "type": "NATIONAL_ID"
    },
    "address": {
      "street_line_1": "Calle 93 #11-27",
      "street_line_2": "Oficina 402",
      "city": "Bogota",
      "state": "Cundinamarca",
      "zip": "110221",
      "country": "CO"
    }
  },
  "beneficial_owners": [
    {
      "first_name": "Wei",
      "last_name": "Chen",
      "dob": "1979-04-02",
      "email": "[email protected]",
      "phone_number": "+6591234567",
      "ownership_percentage": "35",
      "identity": {
        "number": "S1234567D",
        "type": "NATIONAL_ID"
      },
      "address": {
        "street_line_1": "1 Raffles Place",
        "city": "Singapore",
        "zip": "048616",
        "country": "SG"
      }
    }
  ],
  "tos_attestation": {
    "version": "2025-04-01",
    "accepted_at": "2026-05-13T20:45:15Z"
  }
}

The Singaporean owner above omits state entirely, which is what to do for a country with no subdivision to give. Owners and controllers can be mixed: a US controller sending ssn alongside an owner outside the US sending identity is a valid request.

Creating an individual account

On the individual path, set entity_type to individual and account_type to transactional. The individual object and tos_attestation are required. Business-only fields (business_name, ein, website, business_controller, beneficial_owners) must not be sent — they are rejected on this path. POST https://api.brale.xyz/accounts

Request

{
  "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": "Des Moines",
      "state": "IA",
      "zip": "50309"
    },
    "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 ..."
  }
}

The created account’s name is derived from the individual’s first and last name.

Individual account — Required vs. Optional Fields

Field	Type	Required	Description
`entity_type`	string	Yes (for this path)	Must be `individual`.
`account_type`	string	Yes (for this path)	Must be `transactional`.
`verification_mode`	string	No	`standard` (default) or `reliance`.
`individual.first_name`	string	Yes	Legal first name.
`individual.last_name`	string	Yes	Legal last name.
`individual.date_of_birth`	string	Yes	ISO date, `YYYY-MM-DD`.
`individual.email`	string	Yes	Contact email for the individual.
`individual.phone_number`	string	Yes	Accepts common formats (digits only, dashed, with country code).
`individual.country`	string	Yes	Top-level jurisdiction used for verification. Separate from `individual.address`. When `US` or `USA`, `individual.address.state` must be a valid US state or territory.
`individual.address.street_line_1`	string	Yes
`individual.address.street_line_2`	string	No	Apt / Suite / Floor.
`individual.address.city`	string	Yes
`individual.address.state`	string	US only	Required when `individual.country` is `US` or `USA`, and must be a valid state or territory (abbreviated, e.g. `NY`). Optional for non-US individuals, since many countries have no state or province; free-form and not validated when supplied. A blank value is treated as absent.
`individual.address.zip`	string	Yes	Postal code. Any format is accepted, so non-US postal codes are supported.
`individual.address.country`	string	No	Optional. The verification jurisdiction comes from the top-level `individual.country`, not from this field.
`individual.identity.number`	string	Yes	The government identifier value. For US individuals with `type: SSN9`, the 9-digit Social Security number.
`individual.identity.type`	string	Yes	The kind of identifier submitted. One of the values in Identity types below.
`tos_attestation`	object	Yes	Consent record. See Presenting the Brale End-User Agreement.
`doc_submission_ids`	array of strings (KSUID)	No	Optional pre-staged verification documents. Works the same way it does for business accounts.

Identity types

One identity is submitted per person. Use SSN9 for a US taxpayer, or the matching document type for someone outside the US. The same values apply wherever an identity object is accepted: an individual account, and a business controller or beneficial owner.

Region	Accepted `identity.type` values
United States	`SSN9`, `SSN4`, `DRIVER_LICENSE`, `TAX_ID`, `ALIEN_CARD`
International	`PASSPORT`, `NATIONAL_ID`, `VOTER_ID`, `RESIDENT_ID`, `DRIVER_LICENSE`
Nigeria	`BVN`, `NIN`, `NIN_SLIP`
Ghana	`GHANA_CARD_NUMBER`, `SSNIT`
Kenya	`KENYA_KRA_PIN`
Colombia	`COLOMBIA_PPT`

The region column is guidance on which value to send, not a separate validation: any value in this list is accepted. Jurisdiction comes from the country on the person, individual.country for an individual account and address.country for a controlling party.

Creating a non-US individual account

Non-US individuals are supported. individual.address.state is optional and free-form, and the postal code accepts any format, so only the identity type and country change. Omit state for countries that have no state or province:

Request

{
  "entity_type": "individual",
  "account_type": "transactional",
  "individual": {
    "first_name": "Amara",
    "last_name": "Okafor",
    "date_of_birth": "1988-07-22",
    "email": "[email protected]",
    "phone_number": "+2348012345678",
    "country": "NG",
    "address": {
      "street_line_1": "12 Awolowo Road",
      "city": "Lagos",
      "state": "Lagos",
      "zip": "101233"
    },
    "identity": {
      "number": "22222222222",
      "type": "BVN"
    }
  },
  "tos_attestation": {
    "version": "2025-04-01",
    "accepted_at": "2026-05-13T20:45:15Z"
  }
}

What a transactional account cannot do

Transactional accounts are inbound by design. The following constraints are enforced, not conventional:

No Brale-custodied wallets, ever. A transactional account has no automatic custodial wallet at creation and cannot hold internal (type=internal) addresses.
External addresses are destination-only. An external address on a transactional account can receive value but cannot be the source of a transfer.
The account cannot originate an on-chain transfer. An attempt returns 422 with type compatible_address_not_found. Checking the address balance first does not predict this, because the constraint is about the address role, not funds.
Automations from a transactional account may only target external destinations. A Brale-custodied destination is rejected.

The supported shape today is inbound: the account receives value on chain and can be the destination of an on-ramp. See Individual accounts for the end-to-end workflow.

Common Errors when creating Accounts

HTTP Status	Code	Message	Potential Cause	Fix
`422`	`Unprocessable Entity`	Invalid format for business or controller information	Phone number area code is not valid	Include valid area code

Business path errors

HTTP	Error type	Cause
`400`	`controlling_party_identity_required`	A controller or beneficial owner sent neither `ssn` nor `identity`.
`400`	`invalid_controlling_party_identity`	Both `ssn` and `identity` were sent, or `ssn` was sent for a party whose `address.country` is not the US.
`422`	`invalid_country_code`	An `address.country` that is not a recognized ISO country code or name.
`422`	`invalid_us_state`	`address.country` is the US and `address.state` is missing, blank, or not a recognized state or territory.
`400`	`invalid_phone_number`	A `phone_number` that is not valid in that party’s `address.country`.

Individual path errors

HTTP	Error type	Cause
`422`	`unsupported_account_combination`	Dimension combination outside the supported rows (for example, individual + custodial). Permanent; safe to cache against an idempotency key.
`400`	`individual_details_required`	`entity_type: individual` with no `individual` object.
`400`	`tos_attestation_required`	Individual path with no `tos_attestation`.
`400`	`unexpected_business_fields`	A business-only field was sent on the individual path (`business_name`, `ein`, `website`, `business_controller`, `beneficial_owners`).
`422`	`invalid_us_state`	`individual.country` is `US` or `USA` and `individual.address.state` is missing, blank, or not a recognized state or territory.
`400`	`invalid_attestation_timestamp`	`tos_attestation.accepted_at` is not an ISO-8601 timestamp.

Account Status

Brale will review the Account and return a status field denoting the customer’s verification status (KYB for business accounts, KYC for individual accounts). If the customer is in a pending status, you will need to wait for the customer to be verified before creating or linking addresses or bank accounts. GET https://api.brale.xyz/accounts/:id

Response

{
  "id": "2VcUIIsgARwVbEGlIYbhg6fGG57",
  "name": "ABC Company",
  "status": "pending",
  "created": "2023-09-19T14:46:20"
}

Account Statuses

Value	Description
`pending`	Verification is in progress (KYB for business accounts, KYC for individual accounts)
`complete`	Verification is completed and the account is approved
`rejected`	The account’s verification was rejected

Verification

Account verification is asynchronous. After creating an account, Brale reviews the submitted information — KYB for business accounts, KYC for individual accounts. The lifecycle and webhook events are identical in shape across both. Two integration patterns are supported. Proactive (at onboarding): Stage documents, then either pass doc_submission_ids when creating the account or link them later. Reactive (documents requested during review): When Brale needs additional documents, subscribe to the account.verification.documents_required webhook event (see Webhook Events). The payload lists each required document (document_kind, display_name, person_label, status). Stage the files, then link them. Alternatively, poll required documents.

Create account → Brale reviews → [documents required?]
  → Yes: webhook account.verification.documents_required
    → Stage document → Link to account
  → Brale re-reviews → account.verification.completed (status: complete)
                     or account.verification.rejected  (status: rejected)

When verification succeeds, Brale emits account.verification.completed and the account status transitions to complete. When it is declined, Brale emits account.verification.rejected and status becomes rejected. A decline is terminal. The account will not reach complete on its own and uploading further documents does not reopen it, so do not keep polling a rejected account. Contact Brale if you believe a decline is incorrect.

Using Account ID in every request

All resources in the Brale API (Addresses, Financial Institutions, Transfers, Automations, etc.) are scoped to specific accounts. Supply the ID in the path, never in the body.

Every endpoint that contains {account_id} must be called by including the account ID in the path. E.g. GET https://api.brale.xyz/accounts/2Js1YFqlfxgNqC2KTPEjrWIwKU7/addresses. Do not send the account ID in the body or query string.

Overview

Key concepts

Webhooks

Account dimensions

Creating a business account

Presenting the Brale End-User Agreement

Business account — Required vs. Optional Fields

Non-US controllers and beneficial owners

Creating an individual account

Individual account — Required vs. Optional Fields

Identity types

Creating a non-US individual account

What a transactional account cannot do

Common Errors when creating Accounts

Business path errors

Individual path errors

Account Status

Account Statuses

Verification

Using Account ID in every request

​Account dimensions

​Creating a business account

​Presenting the Brale End-User Agreement

​Business account — Required vs. Optional Fields

​Non-US controllers and beneficial owners

​Creating an individual account

​Individual account — Required vs. Optional Fields

​Identity types

​Creating a non-US individual account

​What a transactional account cannot do

​Common Errors when creating Accounts

​Business path errors

​Individual path errors

​Account Status

​Account Statuses

​Verification

​Using Account ID in every request

Account dimensions

Creating a business account

Presenting the Brale End-User Agreement

Business account — Required vs. Optional Fields

Non-US controllers and beneficial owners

Creating an individual account

Individual account — Required vs. Optional Fields

Identity types

Creating a non-US individual account

What a transactional account cannot do

Common Errors when creating Accounts

Business path errors

Individual path errors

Account Status

Account Statuses

Verification

Using Account ID in every request