Skip to main content
POST
/
apex
/
accounts
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"
  }'

{
  "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"
  }
}

​
Request body

​
request_id
string
required
A client-generated UUID that uniquely identifies this account creation request. Use the same value when polling for status.
​
description
string | null
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.
​
status
string
Always "ready".
​
request_id
string
The request_id you provided in the request.
​
account
object
The canonical account record.
​
staging_account
object
The staging record for the Apex account.
​
staging_person
object
The staging record for the associated Apex person.

​
202 - Account creation pending

Returned when account creation cannot complete immediately and is continuing in the background.
​
code
string
Always "apex_account_pending".
​
request_id
string
The request_id you provided in the request.
​
poll_path
string
The path to poll for the account creation status (for example, "/apex/accounts/by-request/{request_id}").

​
Error responses

StatusDescription
403The brokerage account feature is not enabled for your account.
409Required identity data is missing or the local account record cannot be resolved.
423Identity verification must be completed before creating a brokerage account.
428A passkey or recent passkey verification is required.
500The brokerage service is not configured or the request failed.
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"
  }'

{
  "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"
  }
}
Last modified on April 16, 2026