KYC Document Verification

The document upload endpoint allows you to submit compliance and identity documents directly to a Buildmarkets brokerage account. This is used during account onboarding when a user’s KYC (Know Your Customer) review requires supporting documentation, and during ongoing account maintenance for remediation requests or regulatory requirements. Uploaded documents are associated with the specified account and routed to the appropriate compliance workflow.

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 "Authorization: Bearer $BUILDMARKETS_API_KEY" \
  -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 "Authorization: Bearer $BUILDMARKETS_API_KEY" \
  -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 "Authorization: Bearer $BUILDMARKETS_API_KEY" \
  -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

W-9 Requests Documentation

Overview

The W-9 endpoint enables automated generation of IRS Form W-9 (Request for Taxpayer Identification Number and Certification) for specified users. As the documentation states, “W-9s are required for U.S. persons and entities to certify their taxpayer identification number.”

Key Endpoint

POST /v1/documents/w9 — Initiates W-9 generation for a user

Request Details

The endpoint requires a single query parameter:

userId (string, UUID format) — The unique identifier for the user

Important: The userId passes as a query parameter, not in the request body. No request payload is needed.

Response Structure

A successful request (200 OK) returns:

successful (boolean) — Confirms request acceptance
message (string) — Status confirmation text

Processing Timeline

The endpoint confirms immediate receipt, but form generation occurs asynchronously. Users can later retrieve the completed W-9 using the document listing endpoint with documentTypeID: 3 and the relevant year.

Error Scenarios

Common failures include invalid/malformed UUIDs (400), missing API credentials (401), non-existent users (404), and server-side failures (500).

Generation vs. Upload

Two distinct workflows exist: using this endpoint to generate forms from stored data, or uploading pre-signed documents users complete independently.

​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

​W-9 Requests Documentation

​Overview

​Key Endpoint

​Request Details

​Response Structure

​Processing Timeline

​Error Scenarios

​Generation vs. Upload

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

W-9 Requests Documentation

Overview

Key Endpoint

Request Details

Response Structure

Processing Timeline

Error Scenarios

Generation vs. Upload