> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brale.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Accounts
> Accounts represent KYB-verified business entities with `account_id` values used to scope API requests and manage custodial wallets.
Accounts are represented by `account_id` values, which are assigned to KYB'd (business) 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.
Each `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`). The legacy `financial_institution_id` is deprecated — new integrations should use `address_id` and the [Addresses](/key-concepts/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 an account, we collect key details such as business name and EIN. For more information, see our Compliance Requirements. If additional details are required, we will notify you with the necessary steps to complete KYB.
Customers can also self onboard at [https://app.brale.xyz/signup](https://app.brale.xyz/signup).
## Creating an account
You are required to pass in business information, controller information, and ultimate beneficial owner information.
**POST** `https://api.brale.xyz/accounts`
```json Request theme={null}
{
"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": "12345"
},
"phone_number": "2134678902",
"email": "mark@example.com",
"website": "abccompany.com",
"business_controller": {
"first_name": "John",
"last_name": "Doe",
"ssn": "222-22-2222",
"dob": "1981-01-25",
"email": "john@company.com",
"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": "bob@skylineanalytics.io",
"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](https://brale.xyz/legal/end-user-agreement).
## Accounts - 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. API accepts U.S.-based controllers only; email [support@brale.xyz](mailto:support@brale.xyz) if your controller is non-U.S. and we'll process manually. |
| `beneficial_owners` | array | Yes | Individual with ≥25% ownership |
| `tos_attestation` | object | Yes | |
## 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 |
## Account Status
Brale will review the Account and return a `status` field denoting the customer's KYB status. 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`
```json Response theme={null}
{
"id": "2VcUIIsgARwVbEGlIYbhg6fGG57",
"name": "ABC Company",
"status": "pending",
"created": "2023-09-19T14:46:20"
}
```
### Account Statuses
| Value | Description |
| ---------- | -------------------------------------------- |
| `pending` | KYB is in progress |
| `complete` | KYB is completed and the account is approved |
| `rejected` | The account's KYB was rejected |
## 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.