> ## 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.

# Accounts

> The Accounts API is the core of Buildmarkets, covering account types, endpoints, statuses, KYC, listing, updating, and closing accounts.

## Introduction

The Accounts API serves as the core foundation of Buildmarkets. Every end-user brokerage account is represented as an account resource, with all trading, funding, and document activity organized beneath it.

## What is an Account?

A Buildmarkets account is "a fully-managed brokerage account for one of your end users." When creating an account, you submit identity, contact, suitability, and disclosure information on the user's behalf. The system then handles KYC/AML verification, agreement tracking, account status management, and real-time position and balance custody.

## Account Types

* **individual** — Standard individual brokerage account (default)
* **joint** — Joint account requiring a `joint_owner` object in the creation request

## Account Endpoints

| Method | Endpoint                                      | Purpose                                     |
| ------ | --------------------------------------------- | ------------------------------------------- |
| POST   | `/v1/accounts`                                | Create new brokerage account                |
| GET    | `/v1/accounts`                                | List all accounts (paginated, filterable)   |
| GET    | `/v1/accounts/{accountId}`                    | Get full account details                    |
| PATCH  | `/v1/accounts/{accountId}`                    | Update contact, identity, or profile fields |
| POST   | `/v1/accounts/{accountId}/actions/close`      | Initiate account closure                    |
| GET    | `/v1/accounts/{accountId}/balances`           | Get cash and equity balances                |
| GET    | `/v1/accounts/{accountId}/positions`          | List all open positions                     |
| GET    | `/v1/accounts/{accountId}/positions/{symbol}` | Get specific position by symbol             |

## Account Statuses

| Status            | Meaning                                             |
| ----------------- | --------------------------------------------------- |
| SUBMITTED         | Account created and submitted for KYC review        |
| ACTION\_REQUIRED  | Additional information needed before KYC completion |
| APPROVAL\_PENDING | KYC in progress with manual review underway         |
| APPROVED          | KYC approved; account being activated               |
| ACTIVE            | Account fully open for trading and funding          |
| REJECTED          | KYC rejected; account cannot activate               |
| ACCOUNT\_CLOSED   | Account closed; no further activity permitted       |

### KYC Statuses

The `kyc_status` field provides granular visibility into identity verification:

| Status         | Meaning                                      |
| -------------- | -------------------------------------------- |
| SUBMITTED      | Identity data awaiting processing            |
| APPROVED       | Identity verified                            |
| REJECTED       | Identity could not be verified               |
| MANUAL\_REVIEW | Requires Buildmarkets compliance team review |

### Sandbox Testing

Control KYC outcomes using SSN suffixes:

| Suffix | Result             |
| ------ | ------------------ |
| 0001   | APPROVED (instant) |
| 0002   | REJECTED           |
| 0003   | MANUAL\_REVIEW     |

## Listing Accounts

The list endpoint supports pagination, filtering, and sorting.

**Query Parameters:** `query` (search by name or account number), `status` (filter by account status), `created_after` / `created_before` (ISO 8601), `sort` (e.g., `created_at:desc`), `cursor` (pagination cursor), `limit` (default 25, max 100).

**Example Response:**

```json theme={"system"}
{
  "data": [
    {
      "id": "b3f2c9a1-4d5e-4a2f-8b3c-1e2d3f4a5b6c",
      "account_number": "ACC123456789",
      "status": "ACTIVE",
      "kyc_status": "APPROVED",
      "currency": "USD",
      "last_equity": "12450.75",
      "created_at": "2025-06-01T12:00:00Z",
      "account_type": "individual",
      "enabled_assets": ["equity"]
    }
  ],
  "pagination": { "next_cursor": "eyJpZCI6ImIzZjJjOWExIn0=", "has_more": true }
}
```

## Updating an Account

Use `PATCH /v1/accounts/{accountId}` to modify mutable fields. Immutable fields like `date_of_birth` and `tax_id` cannot be changed post-creation. **Mutable Fields:** `contact`, `identity` (limited), `disclosures`, `trusted_contact`, `employment`, `investment_profile`, `registered_rep_code`.

```bash theme={"system"}
curl -X PATCH https://dev-tapp-api.tappengine.com/v1/accounts/ACCOUNT_ID \
  -H "X-API-Key: YOUR_API_KEY" -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "contact": { "email_address": "new@example.com", "city": "Austin", "state": "TX", "postal_code": "78702" } }'
```

## Closing an Account

Accounts must have zero balances (all positions liquidated and funds withdrawn) before closure. The POST action endpoint transitions the account status to `ACCOUNT_CLOSED` and returns `204 No Content` on success.

```bash theme={"system"}
curl -X POST https://dev-tapp-api.tappengine.com/v1/accounts/ACCOUNT_ID/actions/close \
  -H "X-API-Key: YOUR_API_KEY" -H "X-API-Secret: YOUR_API_SECRET"
```

## Next Steps

Related documentation includes Account Opening, Balances & Positions, and Funding Overview guides.