Skip to main content
This page introduces the core concepts, data model, and conventions used throughout the Buildmarkets API. Reading this before diving into feature-specific guides will save you significant time.

​
Core concepts

​
Partners

You — the company integrating Buildmarkets. Partners authenticate with the API using key pairs (X-API-Key / X-API-Secret) scoped to their tenant. All accounts, orders, and funding activity created through your API keys are associated with your partner account.

​
Accounts

A Buildmarkets account represents one end-user brokerage account. Each account holds an identity (KYC data: name, DOB, SSN), contact information (address, phone, email), regulatory disclosures and signed agreements, an investment profile (suitability data), and positions, balances, orders, and funding activity. Accounts are the central resource in the Buildmarkets Wealth API. Almost every other resource — orders, positions, funding — is scoped under GET /v1/accounts/{accountId}/....

​
Orders

An order is an instruction to buy or sell a security. Buildmarkets supports equity and ETF orders with market, limit, stop, and stop-limit order types. Orders go through a lifecycle of states and generate executions (fills) once matched.

​
ACH Relationships

An ACH relationship links a customer’s external bank account to their Buildmarkets brokerage account. It is a prerequisite for funding. Once linked, you can initiate deposits (money into the brokerage account) and withdrawals (money back to the bank).

​
Webhooks

Webhooks are HTTP callbacks that Buildmarkets fires to your server when significant events occur — an account’s KYC status changes, an order is filled, or a deposit settles. Webhooks are the recommended way to stay in sync with state changes rather than polling.

​
Data model overview

Partner (you) holds API Keys (credentials) and Accounts[]. Each Account contains Contact, Identity, Disclosures, Agreements[], InvestmentProfile, TradingConfigurations, Balances, Positions[], Orders[] (each with Executions[]), ACH Relationships[], and Funding Activity[]. Webhooks are partner-level. Market Data is partner-level (not account-scoped). Documents are partner-level plus account-level uploads.

​
API conventions

​
REST & JSON

The Buildmarkets API is a REST API. All request and response bodies are JSON. Set Content-Type: application/json on all requests with a body.

​
Authentication

Every request must include two headers: 
X-API-Key: <your-api-key>
X-API-Secret: <your-api-secret>
See Authentication Overview for how to generate and manage API keys.

​
IDs

  • accountId — UUID string, e.g. "b3f2c9a1-4d5e-4a2f-8b3c-1e2d3f4a5b6c"
  • orderId — UUID string
  • achId — UUID string
  • webhookId — UUID string
Always store and pass IDs as strings. Do not treat them as integers or attempt to sort them numerically.

​
Timestamps

All timestamps are ISO 8601 strings in UTC, e.g. "2025-06-01T14:32:00Z". When submitting timestamps (e.g., signed_at on agreements), use this format.

​
Monetary amounts

Dollar amounts (balances, order quantities, transfer amounts) are represented as decimal strings, not floating-point numbers. This avoids precision loss on monetary values. 
{ "amount": "1000.00" }

​
Pagination

List endpoints that return multiple records use cursor-based pagination. The response shape is: 
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6IjEyMyJ9",
    "has_more": true
  }
}
Pass cursor=<next_cursor> as a query parameter to fetch the next page. Use limit to control page size.

​
Idempotency

For POST requests that initiate financial operations (orders, deposits, withdrawals), use the client_order_id or equivalent idempotency field to safely retry without duplicate execution.

​
Sandbox testing

In the sandbox environment (https://dev-tapp-api.tappengine.com), KYC outcomes are controlled by the SSN suffix you provide when creating an account:
SSN suffixOutcome
0001APPROVED
0002REJECTED
0003MANUAL_REVIEW
For example, SSN 111-22-0001 will result in an immediately approved account. All other sandbox behavior (order fills, funding transfers) is also simulated — no real money or real orders are involved.

​
Next steps

  • Getting Started — Step-by-step guide to your first API call
  • Authentication Overview — Generating and managing API keys
  • Use Cases — Common integration patterns