Skip to main content

​
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. Requires a joint_owner object describing the second account holder, on both POST /v1/accounts and POST /v1/users/{userId}/accounts
  • ira_traditional — Traditional IRA retirement account
  • ira_roth — Roth IRA retirement account
  • custodial — Custodial account opened on behalf of a minor

​
Account Endpoints

​
Multiple Accounts per User

Each account belongs to a user — the verified person behind it. The first POST /v1/accounts call creates both the user profile and their first account; the account response includes a user_id field referencing that user. Once any of a user’s accounts passes KYC, the user is considered KYC-approved and can open additional accounts without repeating document verification:
  • Call POST /v1/users/{userId}/accounts with only the account_type (e.g., a second individual account, or an ira_roth alongside an existing individual). A joint account also needs a joint_owner object.
  • Identity fields are locked to the stored, verified user profile — sending an identity object is rejected.
  • Optional sections (contact, disclosures, agreements, investment_profile, etc.) may be provided to override the stored values; anything omitted falls back to the user’s profile.
  • Document verification is skipped — the existing KYC approval carries over, and the account is booked on the clearing system directly.
If the user’s KYC is not yet approved, the request fails with 409 USER_KYC_NOT_APPROVED.

​
Account Statuses

​
KYC Statuses

The kyc_status field provides granular visibility into identity verification: The account response also includes a kyc_results object with the verification outcome: summary (pass, fail, or indeterminate), reject (a list of rejection reason labels), and additional_information. It is null while the review is still in progress.

​
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:

​
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.
Fields inside contact are individually optional on a PATCH, with one exception: if you send a contact object at all, it must include a valid phone_number (7–25 characters, with country code).

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

​
Next Steps

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