# Create Virtual Account
Creates a Virtual Account for a new customer.
# OpenAPI definition
```json
{
"info": {
"title": "Webull Open API Reference",
"description": "application.yml\\ncom\\ni18n\\nMETA-INF\\nstatic\\n\\r\\n",
"contact": {
"name": "",
"url": "",
"email": ""
},
"version": "2.0",
"x-logo": {
"url": "static/png/logo.png"
}
},
"servers": [
{
"url": "https://broker-api.sandbox.webull.hk"
}
],
"path": "/broker/accounts/virtual-accounts/create",
"method": "post",
"tags": [
"Account (ND)"
],
"description": "Creates a Virtual Account for a new customer.",
"operationId": "brokerAccountCreate",
"parameters": [
{
"name": "x-app-key",
"in": "header",
"description": "A unique identifier issued to a developer for accessing an application's API.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "x-app-secret",
"in": "header",
"description": "A unique key issued to developers to access the application's API.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "x-timestamp",
"in": "header",
"description": "Timestamp of the request, follows ISO8601 format: YYYY-MM-DDThh:mm:ssZ, e.g. 2023-07-16T19:23:51Z, only supports UTC time zone.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "x-signature-version",
"in": "header",
"description": "Signature algorithm version, default is 1.0.",
"required": true,
"schema": {
"type": "string",
"default": "1.0"
},
"examples": {
"1.0": {
"value": "1.0"
}
}
},
{
"name": "x-signature-algorithm",
"in": "header",
"description": "Signature algorithm, default is HMAC-SHA1.",
"required": true,
"schema": {
"type": "string",
"default": "HMAC-SHA1"
},
"examples": {
"HMAC-SHA1": {
"value": "HMAC-SHA1"
}
}
},
{
"name": "x-signature-nonce",
"in": "header",
"description": "Signature unique random number.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "x-version",
"in": "header",
"description": "API interface version. Supported values: `v2`, `v3`.",
"required": true,
"schema": {
"type": "string",
"default": "v3"
},
"examples": {
"v3": {
"value": "v3"
}
}
},
{
"name": "x-signature",
"in": "header",
"description": "A signature is a unique digital fingerprint, typically encrypted, that verifies the authenticity and integrity of a message or transaction, ensuring it has not been tampered with during transmission.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": [
"account_type",
"belong_account_id",
"client_request_id",
"trading_permissions"
],
"type": "object",
"properties": {
"client_request_id": {
"type": "string",
"description": "Client Request ID, unique for each request.
Maximum length is 32 characters.
Allowed characters: letters (A–Z, a–z), digits (0–9), hyphen (-), underscore (_).",
"example": "LJIS16BACHQG9LPP44L9IQHGAB"
},
"belong_account_id": {
"type": "string",
"description": "Belonging Account ID, the master account under which the VA account is created",
"example": "TUHO91TNJ6B870VJ2SUL65U4LB"
},
"external_account_number": {
"type": "string",
"description": "The account number of the end customer in your own system, used as the client-defined segment of the virtual account number. The final account_number is composed as: V + Entity Code + this value, where the Entity Code is assigned by Webull during onboarding.
Example: Entity Code ABCD + 10000001 → VABCD10000001.
• Length: 1-10 characters.
• Allowed characters: ASCII digits (0-9), English letters (a-z, A-Z), hyphen (-) and underscore (_).
• Case-sensitive: ab123 and AB123 are treated as different accounts.
• Leading zeros are significant: 00123 and 123 are different accounts.
• No sequential or other format requirement beyond the above — any value is accepted as long as it is unique within your entity (which makes the composed account_number globally unique).
• Immutable after account creation.
• If omitted, the account number is generated by the system.
The composed account_number is used consistently across order placement (FIX Tag 1), queries, and SOD reconciliation files.",
"example": "0000000001"
},
"account_type": {
"type": "string",
"description": "Account Type
CASH: Cash Account
MARGIN: Margin Account",
"example": "CASH",
"enum": [
"CASH",
"MARGIN"
]
},
"trading_permissions": {
"type": "array",
"description": "Trading Permissions for the VA account, list of permission codes",
"example": [
"US_STOCK_NORMAL"
],
"items": {
"type": "string",
"description": "Trading Permission
US_STOCK_NORMAL - US Stock Normal Trading Permission
HK_STOCK_NORMAL - HK Stock Normal Trading Permission
US_OPTION_NORMAL - US Option Normal Trading Permission
CN_STOCK_NORMAL - CN Stock Trading Permission",
"example": "[\"US_STOCK_NORMAL\"]",
"enum": [
"US_STOCK_NORMAL",
"HK_STOCK_NORMAL",
"CN_STOCK_NORMAL",
"US_OPTION_NORMAL"
]
}
},
"option_level": {
"type": "string",
"description": "The option level must be less than or equal to the option level of the master account.When the trading_permissions contains US_OPTION_NORMAL, it needs to be filled in",
"example": "LV1",
"enum": [
"LV1",
"LV2",
"LV3",
"LV4"
]
},
"commission_code": {
"type": "string",
"description": "Commission Code for the VA account, determining the commission structure.The specific value of the Commission Code needs to be confirmed with the Webull business team, as it determines how commissions will be charged.\n\n",
"example": "COMMISSION_GROUP_1",
"enum": [
"COMMISSION_GROUP_1",
"COMMISSION_GROUP_2",
"COMMISSION_GROUP_3",
"COMMISSION_GROUP_4",
"COMMISSION_GROUP_5"
]
},
"w8ben_info": {
"required": [
"first_name",
"home_address",
"last_name",
"mail_address",
"sign_date",
"tax_id",
"treaty_country"
],
"type": "object",
"properties": {
"treaty_country": {
"type": "string",
"description": "Country of Treaty, using ISO 3166-1 alpha-2 format",
"example": "US"
},
"tax_id": {
"type": "string",
"description": "Tax Identification Number",
"example": "123-45-6789"
},
"sign_date": {
"type": "string",
"description": "W-8BEN Form Sign Date, format: YYYY-MM-DD",
"example": "2026-01-01"
},
"first_name": {
"type": "string",
"description": "First Name of the account holder",
"example": "John"
},
"last_name": {
"type": "string",
"description": "Last Name of the account holder",
"example": "Doe"
},
"middle_name": {
"type": "string",
"description": "Middle Name of the account holder",
"example": "Michael"
},
"home_address": {
"required": [
"city",
"country",
"postal_code",
"state",
"street_address"
],
"type": "object",
"properties": {
"country": {
"type": "string",
"description": "Country, using ISO 3166-1 alpha-2 format",
"example": "US"
},
"state": {
"type": "string",
"description": "State or Province",
"example": "California"
},
"city": {
"type": "string",
"description": "City",
"example": "Central"
},
"street_address": {
"type": "string",
"description": "Street Address",
"example": "1 Queen's Road"
},
"postal_code": {
"type": "string",
"description": "Postal Code",
"example": "999077"
}
},
"description": "W-8BEN Address Information",
"title": "W8BenAddress"
},
"mail_address": {
"required": [
"city",
"country",
"postal_code",
"state",
"street_address"
],
"type": "object",
"properties": {
"country": {
"type": "string",
"description": "Country, using ISO 3166-1 alpha-2 format",
"example": "US"
},
"state": {
"type": "string",
"description": "State or Province",
"example": "California"
},
"city": {
"type": "string",
"description": "City",
"example": "Central"
},
"street_address": {
"type": "string",
"description": "Street Address",
"example": "1 Queen's Road"
},
"postal_code": {
"type": "string",
"description": "Postal Code",
"example": "999077"
}
},
"description": "W-8BEN Address Information",
"title": "W8BenAddress"
}
},
"description": "W-8BEN Information,When trading U.S. stocks in the account, this information needs to be supplemented.\n\n",
"title": "W8BenInfoCreateRequest"
},
"china_connect_investor_info": {
"required": [
"country_of_issuance",
"first_name",
"id_number",
"id_type",
"last_name"
],
"type": "object",
"properties": {
"first_name": {
"type": "string",
"description": "First Name",
"example": "John"
},
"last_name": {
"type": "string",
"description": "Last Name",
"example": "Doe"
},
"middle_name": {
"type": "string",
"description": "Middle Name",
"example": "Michael"
},
"id_type": {
"type": "string",
"description": "ID Type
ID_CARD: Identification Card
PASSPORT: Passport
CERT_INCORP: Certificate of Incorporation
LEI: Legal Entity Identifier
OTHER_OFFICIAL_ID_DOC: Other Official ID Document",
"example": "ID_CARD",
"enum": [
"ID_CARD",
"PASSPORT",
"CERT_INCORP",
"LEI",
"OTHER_OFFICIAL_ID_DOC"
]
},
"id_number": {
"type": "string",
"description": "ID Number",
"example": "X12345678"
},
"country_of_issuance": {
"type": "string",
"description": "Country of Issuance, using ISO 3166-1 alpha-2 format",
"example": "US"
}
},
"description": "China Connect Investor Information,This information only needs to be supplemented when trading Chinese A-shares.\n\n",
"title": "ChinaConnectInvestorInfo"
}
},
"description": "Create VA Account Request",
"title": "AccountVaCreateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"required": [
"account_id",
"account_number",
"account_status",
"client_request_id"
],
"type": "object",
"properties": {
"client_request_id": {
"type": "string",
"description": "Create VA Account Request ID",
"example": "LJIS16BACHQG9LPP44L9IQHGAB"
},
"account_number": {
"type": "string",
"description": "Account Number",
"example": "VA000000001"
},
"account_id": {
"type": "string",
"description": "Account ID",
"example": "943a9802f6c14983b3b4755c69c01717"
},
"account_status": {
"type": "string",
"description": "Account Status
CREATED - Account is created but not yet active
ACTIVE - Account is active and operational
SUSPENDED - Account temporarily suspended
RESTRICTED - Account restricted, limited operations
FROZEN - Account frozen due to compliance or risk
CLOSED - Account permanently closed",
"example": "CREATED",
"enum": [
"CREATED",
"ACTIVE",
"SUSPENDED",
"RESTRICTED",
"FROZEN",
"CLOSED"
]
}
},
"description": "Create VA Account Result",
"title": "AccountVaCreateResult"
}
}
}
},
"401": {
"description": "Unauthorized: Authentication required",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error_code": {
"type": "string",
"description": "Internal logic error code",
"example": "UNAUTHORIZED"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Insufficient permission"
}
}
}
}
}
},
"417": {
"description": "A business logic error triggered when the request cannot be processed due to domain-specific constraints.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error_code": {
"type": "string",
"description": "Internal logic error code",
"example": "INVALID_PARAMETER"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Parameter error, phone"
}
}
}
}
}
},
"500": {
"description": "Internal Server Error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error_code": {
"type": "string",
"description": "Internal logic error code",
"example": "SYSTEM_ERROR"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Internal Server Error"
}
}
}
}
}
}
},
"jsonRequestBodyExample": {
"client_request_id": "LJIS16BACHQG9LPP44L9IQHGAB",
"belong_account_id": "TUHO91TNJ6B870VJ2SUL65U4LB",
"external_account_number": "0000000001",
"account_type": "CASH",
"trading_permissions": [
"US_STOCK_NORMAL"
],
"option_level": "LV1",
"commission_code": "COMMISSION_GROUP_1",
"w8ben_info": {
"treaty_country": "US",
"tax_id": "123-45-6789",
"sign_date": "2026-01-01",
"first_name": "John",
"last_name": "Doe",
"middle_name": "Michael",
"home_address": {
"country": "US",
"state": "California",
"city": "Central",
"street_address": "1 Queen's Road",
"postal_code": "999077"
},
"mail_address": {
"country": "US",
"state": "California",
"city": "Central",
"street_address": "1 Queen's Road",
"postal_code": "999077"
}
},
"china_connect_investor_info": {
"first_name": "John",
"last_name": "Doe",
"middle_name": "Michael",
"id_type": "ID_CARD",
"id_number": "X12345678",
"country_of_issuance": "US"
}
},
"postman": {
"name": "Create Virtual Account",
"description": {
"content": "Creates a Virtual Account for a new customer.",
"type": "text/plain"
},
"url": {
"path": [
"broker",
"accounts",
"virtual-accounts",
"create"
],
"host": [
"{{baseUrl}}"
],
"query": [],
"variable": []
},
"header": [
{
"disabled": false,
"description": {
"content": "(Required) A unique identifier issued to a developer for accessing an application's API.",
"type": "text/plain"
},
"key": "x-app-key",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) A unique key issued to developers to access the application's API.",
"type": "text/plain"
},
"key": "x-app-secret",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) Timestamp of the request, follows ISO8601 format: YYYY-MM-DDThh:mm:ssZ, e.g. 2023-07-16T19:23:51Z, only supports UTC time zone.",
"type": "text/plain"
},
"key": "x-timestamp",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) Signature algorithm version, default is 1.0.",
"type": "text/plain"
},
"key": "x-signature-version",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) Signature algorithm, default is HMAC-SHA1.",
"type": "text/plain"
},
"key": "x-signature-algorithm",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) Signature unique random number.",
"type": "text/plain"
},
"key": "x-signature-nonce",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) API interface version. Supported values: `v2`, `v3`.",
"type": "text/plain"
},
"key": "x-version",
"value": ""
},
{
"disabled": false,
"description": {
"content": "(Required) A signature is a unique digital fingerprint, typically encrypted, that verifies the authenticity and integrity of a message or transaction, ensuring it has not been tampered with during transmission.",
"type": "text/plain"
},
"key": "x-signature",
"value": ""
},
{
"key": "Content-Type",
"value": "application/json"
},
{
"key": "Accept",
"value": "application/json"
}
],
"method": "POST",
"body": {
"mode": "raw",
"raw": "",
"options": {
"raw": {
"language": "json"
}
}
}
}
}
```