> ## Documentation Index
> Fetch the complete documentation index at: https://developer.buildmarkets.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Account Onboarding

> Full field reference and request schema for creating a brokerage account via POST /v1/accounts, including KYC handling and validation errors.

## Endpoint

```
POST /v1/accounts
```

## Required Fields

The minimum required fields to create an account are: `contact` (email, address, city, state, postal code); `identity` (first name, last name, date of birth, SSN/tax ID); `investment_profile` (risk tolerance, investment objective, income and net worth ranges). All other fields are optional but may be required for specific account types or trading features.

## Full Request Schema

### `contact` object

| Field            | Type      | Required | Description                                   |
| ---------------- | --------- | -------- | --------------------------------------------- |
| `email_address`  | string    | ✅        | Primary email address                         |
| `phone_number`   | string    |          | Phone with country code (e.g. `+15125550100`) |
| `street_address` | string\[] |          | Street address lines                          |
| `unit`           | string    |          | Apartment, suite, or unit number              |
| `city`           | string    | ✅        | City                                          |
| `state`          | string    | ✅        | 2-letter state code (e.g. `TX`)               |
| `postal_code`    | string    | ✅        | ZIP code (5 or 9 digits)                      |
| `country`        | string    |          | ISO 2-letter country code. Defaults to `US`   |

### `identity` object

| Field                      | Type      | Required | Description                                                  |
| -------------------------- | --------- | -------- | ------------------------------------------------------------ |
| `given_name`               | string    | ✅        | Legal first name                                             |
| `middle_name`              | string    |          | Middle name or initial                                       |
| `family_name`              | string    | ✅        | Legal last name                                              |
| `date_of_birth`            | string    | ✅        | Date of birth in `YYYY-MM-DD` format                         |
| `tax_id`                   | string    | ✅        | SSN (US residents) or EIN. 9–11 characters, dashes optional. |
| `tax_id_type`              | string    |          | Defaults to `US_SSN`. Other values: `US_EIN`                 |
| `country_of_citizenship`   | string    |          | ISO country code. Defaults to `US`                           |
| `country_of_birth`         | string    |          | ISO country code of birth country                            |
| `country_of_tax_residence` | string    |          | ISO country code for tax residence. Defaults to `US`         |
| `funding_source`           | string\[] |          | Sources of investment funds (e.g. `["employment_income"]`)   |

### `disclosures` object

Regulatory disclosures required by FINRA. All fields default to `false` if omitted: `is_control_person`, `control_person_company_name`, `is_affiliated_exchange_or_finra`, `is_spouse_affiliated_finra`, `is_politically_exposed`, `immediate_family_exposed`.

### `agreements` array

Each agreement must be captured with a timestamp and optionally IP address. The `customer_agreement` is required for all accounts; `margin_agreement` is required if `margin_enabled = true`; `options_agreement` is required if `options_level > 0`.

```json theme={"system"}
"agreements": [ { "agreement": "customer_agreement", "signed_at": "2025-06-01T12:00:00Z", "ip_address": "203.0.113.42" } ]
```

### `investment_profile` object

Required: `risk_tolerance` (`conservative`/`moderate`/`aggressive`), `investment_objective` (`growth`/`income`/`speculation`/`capital_preservation`/`other`), `annual_income_range`, `net_worth_range`, `liquid_net_worth_range`. Optional: `liquidity_needs`, `time_horizon` (`short`/`average`/`long`), `years_trading_stocks`, `years_trading_options`, `stock_experience`, `options_experience`, `income_source`, `funds_source`, `investment_plan`.

### `trading_configurations` object (optional)

`options_level` (0=none, 1=covered calls, 2=spreads, 3=full); `margin_enabled` (requires `margin_agreement`).

### Other optional top-level fields

`account_type` (`individual` default or `joint`), `trusted_contact`, `employment`, `mailing_address`, `joint_owner` (required when `account_type` is `joint`), `dividend_reinvestment`, `discretionary_account`, `registered_rep_code`, `advisor_code`, `corr_metadata` (freeform, up to 255 chars).

## Complete Example Request

```json theme={"system"}
{
  "account_type": "individual",
  "contact": { "email_address": "jane@example.com", "phone_number": "+15125550100", "street_address": ["123 Main Street"], "city": "Austin", "state": "TX", "postal_code": "78701", "country": "US" },
  "identity": { "given_name": "Jane", "middle_name": "M", "family_name": "Doe", "date_of_birth": "1990-04-15", "tax_id": "111-22-0001", "tax_id_type": "US_SSN", "country_of_citizenship": "US", "funding_source": ["employment_income"] },
  "disclosures": { "is_control_person": false, "is_affiliated_exchange_or_finra": false, "is_politically_exposed": false, "immediate_family_exposed": false },
  "agreements": [ { "agreement": "customer_agreement", "signed_at": "2025-06-01T12:00:00Z", "ip_address": "203.0.113.42" } ],
  "investment_profile": { "risk_tolerance": "moderate", "investment_objective": "growth", "annual_income_range": "50000_to_100000", "net_worth_range": "100000_to_250000", "liquid_net_worth_range": "50000_to_100000", "time_horizon": "long" },
  "trading_configurations": { "options_level": 0, "margin_enabled": false },
  "dividend_reinvestment": true,
  "corr_metadata": "internal-user-id-98765"
}
```

## Response

On success, returns `201 Created` with the full `AccountResponse` object including the generated `id` and initial `status`.

```json theme={"system"}
{
  "id": "b3f2c9a1-4d5e-4a2f-8b3c-1e2d3f4a5b6c",
  "account_number": "ACC123456789",
  "status": "SUBMITTED",
  "kyc_status": "SUBMITTED",
  "currency": "USD",
  "last_equity": "0.00",
  "created_at": "2025-06-01T12:00:05Z",
  "account_type": "individual",
  "enabled_assets": ["equity"]
}
```

> **Note:** Newly created accounts start in `SUBMITTED` status. In the sandbox with SSN suffix `0001`, KYC completes rapidly and transitions to `ACTIVE`. In production, KYC processing typically completes in seconds to minutes, but some accounts require manual review.

## Handling KYC Outcomes

Use Webhooks to receive real-time notifications when an account's `status` or `kyc_status` changes. Subscribe to the `account.updated` event and check the new status in the payload. Alternatively, poll `GET /v1/accounts/{accountId}` and check `kyc_status` until it reaches `APPROVED` or `REJECTED`.

## Common Validation Errors

| Error                                           | Cause                                |
| ----------------------------------------------- | ------------------------------------ |
| `MISSING_REQUIRED_FIELD: contact.email_address` | Email address omitted from `contact` |
| `MISSING_REQUIRED_FIELD: identity.tax_id`       | SSN omitted from `identity`          |
| `VALIDATION_ERROR: identity.date_of_birth`      | Date not in `YYYY-MM-DD` format      |
| `MISSING_REQUIRED_FIELD: agreements`            | No agreements array provided         |
| `VALIDATION_ERROR: agreements[0].signed_at`     | Timestamp not in ISO 8601 format     |

## Next Steps

* Account Statuses — Full state machine and transitions
* Balances & Positions — Reading portfolio data after the account is ACTIVE
* Funding Overview — Link a bank account and make a deposit