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 requiring a joint_owner object in the creation request

​
Account Endpoints

MethodEndpointPurpose
POST/v1/accountsCreate new brokerage account
GET/v1/accountsList 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/closeInitiate account closure
GET/v1/accounts/{accountId}/balancesGet cash and equity balances
GET/v1/accounts/{accountId}/positionsList all open positions
GET/v1/accounts/{accountId}/positions/{symbol}Get specific position by symbol

​
Account Statuses

StatusMeaning
SUBMITTEDAccount created and submitted for KYC review
ACTION_REQUIREDAdditional information needed before KYC completion
APPROVAL_PENDINGKYC in progress with manual review underway
APPROVEDKYC approved; account being activated
ACTIVEAccount fully open for trading and funding
REJECTEDKYC rejected; account cannot activate
ACCOUNT_CLOSEDAccount closed; no further activity permitted

​
KYC Statuses

The kyc_status field provides granular visibility into identity verification:
StatusMeaning
SUBMITTEDIdentity data awaiting processing
APPROVEDIdentity verified
REJECTEDIdentity could not be verified
MANUAL_REVIEWRequires Buildmarkets compliance team review

​
Sandbox Testing

Control KYC outcomes using SSN suffixes:
SuffixResult
0001APPROVED (instant)
0002REJECTED
0003MANUAL_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: 
{
  "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. 
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. 
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.