Compliance & KYC

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 or EIN (must be 9 digits for US tax IDs, dashes optional). Foreign identification numbers (`FIN`) may be alphanumeric.
`tax_id_type`	string		Defaults to `USA_SSN`. Other values: `USA_EIN`, `FIN` (foreign identification number for non-US persons)
`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 requested_option_level > 0.

"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/preservation), annual_income_range, net_worth_range, liquid_net_worth_range. Optional: liquidity_needs (low/medium/high), time_horizon (short/medium/long), years_trading_stocks, years_trading_options, stock_experience, options_experience, income_source, funds_source, investment_plan.

`trading_configurations` object (optional)

margin_enabled (requires margin_agreement); short_selling_enabled. Options access is requested via the top-level requested_option_level field (0–4, 0 = no options); the granted level is decided by the approval engine, never by the partner.

`documents` array (identity verification documents)

Government ID image(s) used for identity verification, submitted alongside the application. Each entry is one base64-encoded image:

Field	Type	Required	Description
`document_type`	string		Defaults to `identity_verification`
`document_sub_type`	string	✅	`passport`, `id_card`, or `drivers_license`
`side`	string		`front` or `back` — required for two-sided IDs
`content`	string	✅	Base64-encoded image data
`mime_type`	string		Defaults to `image/jpeg`

A passport requires one entry; id_card and drivers_license require two entries (one front, one back).

Other optional top-level fields

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

Identity Document Verification

Identity documents are verified through Buildmarkets’s KYC process before the account is booked on the clearing system. Both US applicants (tax_id_type of USA_SSN or USA_EIN) and non-US applicants (tax_id_type of FIN) go through the same document-based identity verification. The flow is simple from your perspective: include the government ID image(s) in the documents array of POST /v1/accounts. The account is persisted immediately with status SUBMITTED while the documents go through KYC review. Once the review passes, Buildmarkets automatically submits the application to the clearing system, which runs CIP screening (KYC + OFAC watchlist) and activates the account. Track progress via the status and kyc_status fields or webhooks. If a verification is rejected or cannot complete, the account moves to ACTION_REQUIRED. You can resubmit new document images via PATCH /v1/accounts/{accountId} with a fresh documents array, which re-runs identity verification. Once a user has passed document verification on any account, additional accounts opened for that user via POST /v1/users/{userId}/accounts skip document verification entirely — the existing approval carries over.

Complete Example Request

{
  "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-3344", "tax_id_type": "USA_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": { "margin_enabled": false },
  "documents": [
    { "document_type": "identity_verification", "document_sub_type": "drivers_license", "side": "front", "content": "<base64-encoded image>", "mime_type": "image/jpeg" },
    { "document_type": "identity_verification", "document_sub_type": "drivers_license", "side": "back", "content": "<base64-encoded image>", "mime_type": "image/jpeg" }
  ],
}

Response

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

{
  "id": "b3f2c9a1-4d5e-4a2f-8b3c-1e2d3f4a5b6c",
  "user_id": "7f6e5d4c-3b2a-4190-8f7e-6d5c4b3a2910",
  "account_number": null,
  "status": "SUBMITTED",
  "kyc_status": "submitted",
  "currency": "USD",
  "created_at": "2025-06-01T12:00:05Z",
  "account_type": "individual"
}

Note: Newly created accounts start in SUBMITTED status while identity documents go through KYC review. account_number is null until the account is booked on the clearing system after verification passes. KYC processing typically completes in seconds to minutes, but some accounts require manual review (action_required).

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

Uploading Documents

Important: The only document upload that drives identity verification is the documents array (identity verification documents) submitted with POST /v1/accounts at account creation, or resubmitted via PATCH /v1/accounts/{accountId} when an account is in ACTION_REQUIRED.

The document upload endpoint is intended for submitting compliance and identity documents directly to a Buildmarkets brokerage account during ongoing account maintenance. Live processing of these uploads is not yet available.

Endpoint

Method	Path	Description
`POST`	`/v1/accounts/{accountId}/documents/upload`	Upload a compliance document to an account

Upload a document

Accepts a Base64-encoded file along with its document type classification. The platform processes the upload and associates it with the account for compliance review.

`POST /v1/accounts/{accountId}/documents/upload`

Path parameters

Parameter	Type	Required	Description
`accountId`	string (UUID)	✅	The Buildmarkets account to attach the document to

Request body

Field	Type	Required	Description
`document_type`	string	✅	Classification of the document. See supported types below
`document_sub_type`	string	❌	Free-form sub-classification (e.g., `"passport"`, `"drivers_license"`, `"utility_bill"`)
`content`	string	Conditional	Base64-encoded binary content of the document. Required for all types except `w8ben`. Maximum size: 10MB
`content_data`	object	Conditional	JSON form data. Used only for `w8ben` document type in place of `content`
`mime_type`	string	❌	MIME type of the uploaded file (e.g., `"image/png"`, `"image/jpeg"`, `"application/pdf"`)

Supported `document_type` values

Value	Description
`identity_verification`	Government-issued photo ID (passport, driver’s license, national ID)
`address_verification`	Proof of address (utility bill, bank statement, lease)
`date_of_birth_verification`	Document verifying date of birth
`tax_id_verification`	Document verifying Social Security Number or ITIN
`account_approval_letter`	Approval letter for account opening
`cip_result`	Customer Identification Program result document
`w8ben`	IRS Form W-8BEN (Certificate of Foreign Status) — submitted as `content_data` JSON, not Base64
`w9`	IRS Form W-9 (Request for Taxpayer Identification)
`company_formation`	Certificate of incorporation or equivalent
`entity_operating_document`	Operating agreement or bylaws (for entity accounts)
`entity_registration`	State registration filing
`hio_declaration_form`	Household/Immediate Office declaration form
`limited_trading_authorization`	Authorization for a third party to trade on the account
`pep_declaration_form`	Politically Exposed Person declaration

Response

Returns 204 No Content on success. No body is returned.

Example requests

Identity verification — passport (image)

# First, Base64-encode your file
ENCODED=$(base64 -i passport_scan.png)

curl -X POST https://api.tappengine.com/v1/accounts/b3d9f1a2-4c7e-4f0b-9e2d-1a2b3c4d5e6f/documents/upload \
  -H "X-API-Key: $BUILDMARKETS_API_KEY" -H "X-API-Secret: $BUILDMARKETS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d "{
    \"document_type\": \"identity_verification\",
    \"document_sub_type\": \"passport\",
    \"content\": \"$ENCODED\",
    \"mime_type\": \"image/png\"
  }"

Address verification — utility bill (PDF)

ENCODED=$(base64 -i utility_bill.pdf)

curl -X POST https://api.tappengine.com/v1/accounts/b3d9f1a2-4c7e-4f0b-9e2d-1a2b3c4d5e6f/documents/upload \
  -H "X-API-Key: $BUILDMARKETS_API_KEY" -H "X-API-Secret: $BUILDMARKETS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d "{
    \"document_type\": \"address_verification\",
    \"document_sub_type\": \"utility_bill\",
    \"content\": \"$ENCODED\",
    \"mime_type\": \"application/pdf\"
  }"

W-8BEN — JSON form data

The w8ben document type accepts form data as a JSON object in content_data rather than a Base64-encoded file. The structure mirrors the IRS W-8BEN form fields.

curl -X POST https://api.tappengine.com/v1/accounts/b3d9f1a2-4c7e-4f0b-9e2d-1a2b3c4d5e6f/documents/upload \
  -H "X-API-Key: $BUILDMARKETS_API_KEY" -H "X-API-Secret: $BUILDMARKETS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "w8ben",
    "content_data": {
      "name": "Maria García",
      "country_of_citizenship": "Mexico",
      "permanent_address": "123 Calle Principal, Ciudad de México, MX 06600",
      "mailing_address": "123 Calle Principal, Ciudad de México, MX 06600",
      "date_of_birth": "1985-04-12",
      "foreign_tax_id": "GARM850412XXX",
      "treaty_country": "Mexico",
      "treaty_article": "10",
      "withholding_rate": "10",
      "income_type": "Dividends",
      "signature_date": "2026-03-24"
    }
  }'

Response

HTTP/1.1 204 No Content

File size and format limits

Constraint	Limit
Maximum file size	10MB per upload
Supported image types	`image/png`, `image/jpeg`, `image/gif`, `image/webp`
Supported document types	`application/pdf`
Encoding	Base64 (standard encoding, no line breaks required)

Tip: If you’re encoding in JavaScript, use Buffer.from(fileBuffer).toString('base64'). In Python, use base64.b64encode(file_bytes).decode('utf-8').

Common errors

HTTP Status	Error	Cause
`400`	`INVALID_DOCUMENT_TYPE`	`document_type` is not one of the supported values
`400`	`CONTENT_REQUIRED`	`content` is missing for a non-`w8ben` document type
`400`	`CONTENT_DATA_REQUIRED`	`content_data` is missing for the `w8ben` document type
`400`	`FILE_TOO_LARGE`	Decoded file exceeds the 10MB size limit
`400`	`INVALID_MIME_TYPE`	The `mime_type` is not supported
`404`	`ACCOUNT_NOT_FOUND`	No account found for the provided `accountId`

Next steps

W-9 Requests → — Generate W-9 forms programmatically for a user
Retrieving Documents → — Access documents that have been generated for an account
Account Opening → — Review the KYC fields collected at account creation

Updated 3 months ago

Core Concepts

Infrastructure

Endpoint

Required Fields

Full Request Schema

`contact` object

`identity` object

`disclosures` object

`agreements` array

`investment_profile` object

`trading_configurations` object (optional)

`documents` array (identity verification documents)

Other optional top-level fields

Identity Document Verification

Complete Example Request

Response

Handling KYC Outcomes

Common Validation Errors

Next Steps

Uploading Documents

Endpoint

Upload a document

`POST /v1/accounts/{accountId}/documents/upload`

Path parameters

Request body

Supported `document_type` values

Response

Example requests

Identity verification — passport (image)

Address verification — utility bill (PDF)

W-8BEN — JSON form data

Response

File size and format limits

Common errors

Next steps

​Endpoint

​Required Fields

​Full Request Schema

​contact object

​identity object

​disclosures object

​agreements array

​investment_profile object

​trading_configurations object (optional)

​documents array (identity verification documents)

​Other optional top-level fields

​Identity Document Verification

​Complete Example Request

​Response

​Handling KYC Outcomes

​Common Validation Errors

​Next Steps

​Uploading Documents

​Endpoint

​Upload a document

​POST /v1/accounts/{accountId}/documents/upload

Path parameters

Request body

Supported document_type values

Response

​Example requests

​Identity verification — passport (image)

​Address verification — utility bill (PDF)

​W-8BEN — JSON form data

​Response

​File size and format limits

​Common errors

​Next steps

Endpoint

Required Fields

Full Request Schema

`contact` object

`identity` object

`disclosures` object

`agreements` array

`investment_profile` object

`trading_configurations` object (optional)

`documents` array (identity verification documents)

Other optional top-level fields

Identity Document Verification

Complete Example Request

Response

Handling KYC Outcomes

Common Validation Errors

Next Steps

Uploading Documents

Endpoint

Upload a document

`POST /v1/accounts/{accountId}/documents/upload`

Supported `document_type` values

Example requests

Identity verification — passport (image)

Address verification — utility bill (PDF)

W-8BEN — JSON form data

Response

File size and format limits

Common errors

Next steps