> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yoshi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create brokerage account
> Use POST /apex/accounts to open an Apex-backed brokerage account. Covers request body fields, sync and async responses, and error handling.
## Request body
A client-generated UUID that uniquely identifies this account creation request. Use the same value when polling for status.
An optional label for the brokerage account (for example, `"Long-term investments"`).
## Response
This endpoint returns one of two responses depending on whether the account was created synchronously or is being processed asynchronously.
### 200 - Account created
Returned when the brokerage account is created immediately.
Always `"ready"`.
The `request_id` you provided in the request.
The canonical account record.
Unique account identifier.
Display name of the account.
Account type (for example, `"investment"`).
Account subtype (for example, `"brokerage"`).
Current account status.
External identifier from the brokerage provider.
Source of the external identifier.
The Apex brokerage account number.
Timestamp of the last data update.
When the account was created.
When the account was last updated.
The staging record for the Apex account.
Staging account identifier.
The Apex account number.
Identifier of the associated Apex person.
Current Apex account state.
Account description.
The user who owns this account.
Timestamp of the last data update.
When the staging record was created.
When the staging record was last updated.
The staging record for the associated Apex person.
Staging person identifier.
The user who owns this person record.
Current person status.
When the person record was created.
When the person record was last updated.
### 202 - Account creation pending
Returned when account creation cannot complete immediately and is continuing in the background.
Always `"apex_account_pending"`.
The `request_id` you provided in the request.
The path to poll for the account creation status (for example, `"/apex/accounts/by-request/{request_id}"`).
### Error responses
| Status | Description |
| ------ | --------------------------------------------------------------------------------- |
| 403 | The brokerage account feature is not enabled for your account. |
| 409 | Required identity data is missing or the local account record cannot be resolved. |
| 423 | Identity verification must be completed before creating a brokerage account. |
| 428 | A passkey or recent passkey verification is required. |
| 500 | The brokerage service is not configured or the request failed. |
```bash cURL theme={null}
curl -X POST https://api.yoshi.ai/apex/accounts \
-H "Authorization: Bearer yoshi_3xK9mP..." \
-H "Content-Type: application/json" \
-d '{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"description": "Long-term investments"
}'
```
```python Python theme={null}
import httpx
response = httpx.post(
"https://api.yoshi.ai/apex/accounts",
headers={"Authorization": "Bearer yoshi_3xK9mP..."},
json={
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"description": "Long-term investments",
},
)
data = response.json()
if data.get("status") == "ready":
print(f"Account created: {data['account']['id']}")
else:
print(f"Pending — poll at: {data['poll_path']}")
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.yoshi.ai/apex/accounts", {
method: "POST",
headers: {
Authorization: "Bearer yoshi_3xK9mP...",
"Content-Type": "application/json",
},
body: JSON.stringify({
request_id: "550e8400-e29b-41d4-a716-446655440000",
description: "Long-term investments",
}),
});
const data = await response.json();
if (data.status === "ready") {
console.log(`Account created: ${data.account.id}`);
} else {
console.log(`Pending — poll at: ${data.poll_path}`);
}
```
```json 200 - Ready theme={null}
{
"status": "ready",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"account": {
"id": "acc_brok_abc123",
"name": "Brokerage Account",
"type": "investment",
"subtype": "brokerage",
"status": "active",
"external_id": "ext_apex_456",
"external_source": "apex",
"apex_account_number": "8AA000001",
"as_of": "2026-04-15T12:00:00.000Z",
"created_at": "2026-04-15T12:00:00.000Z",
"updated_at": "2026-04-15T12:00:00.000Z"
},
"staging_account": {
"id": "stg_abc123",
"account_number": "8AA000001",
"apex_person_id": "apx_person_789",
"apex_state": "COMPLETE",
"description": "Long-term investments",
"owner_user_id": "usr_xyz",
"as_of": "2026-04-15T12:00:00.000Z",
"created_at": "2026-04-15T12:00:00.000Z",
"updated_at": "2026-04-15T12:00:00.000Z"
},
"staging_person": {
"id": "stg_person_789",
"owner_user_id": "usr_xyz",
"status": "COMPLETE",
"created_at": "2026-04-15T12:00:00.000Z",
"updated_at": "2026-04-15T12:00:00.000Z"
}
}
```
```json 202 - Pending theme={null}
{
"code": "apex_account_pending",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"poll_path": "/apex/accounts/by-request/550e8400-e29b-41d4-a716-446655440000"
}
```