# Update Account
Submit a request to update an existing account. This API only updates the fields submitted in the forms data. Any attributes not included in the request will remain unchanged.
Related Event Notifications:
Please refer to the Event Push API documentation: [Account Events](../fd-events/account-events)
# 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.com"
}
],
"path": "/broker/accounts/update",
"method": "post",
"tags": [
"Accounts"
],
"description": "Submit a request to update an existing account. This API only updates the fields submitted in the forms data. Any attributes not included in the request will remain unchanged.
Related Event Notifications:
Please refer to the Event Push API documentation: [Account Events](../fd-events/account-events)",
"operationId": "updateAccountApply",
"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": {
"description": "Request payload containing the account details to update.",
"content": {
"application/json": {
"schema": {
"required": [
"account_id",
"client_request_id",
"forms"
],
"type": "object",
"properties": {
"client_request_id": {
"type": "string",
"description": "Unique identifier for the request, generated each time.",
"example": "123e4567e89b12d3a456426614174000"
},
"account_id": {
"type": "string",
"description": "The account ID for which the update is being submitted.",
"example": "943a9802f6c14983b3b4755c69c01717"
},
"forms": {
"type": "array",
"description": "Array of one or more FormData objects representing the account form being submitted. Use form details API to retrieve the form schema and details.",
"items": {
"required": [
"form_info",
"json_data"
],
"type": "object",
"properties": {
"form_info": {
"required": [
"form_code",
"version"
],
"type": "object",
"properties": {
"form_code": {
"type": "string",
"description": "Unique identifier of the form, typically used to distinguish different form definitions.",
"example": "UPDATE_ACCOUNT_FORM"
},
"version": {
"type": "string",
"description": "Version number of the form definition, used for compatibility and evolutionary control.",
"example": "1.0"
}
},
"description": "Form Identifier.",
"title": "UpdateFormId"
},
"json_data": {
"type": "object",
"description": "Object containing the completed form data as defined by the form schema and will vary from form to form. ",
"example": {
"type": "object",
"description": "This form is used to submit post-onboarding account update requests for an existing account. It serves as a unified entry point for multiple account maintenance and compliance-related update scenarios after the account has been successfully opened. The specific update scenario is determined by the `type` field. Based on the selected type, the corresponding update information object must be provided. This form is commonly used for periodic reviews, regulatory compliance verification, risk control follow-ups, and other account data maintenance processes to ensure that account records remain accurate, valid, and up to date.",
"form_code": "ACCOUNT_UPDATE_FORM",
"properties": {
"type": {
"type": "string",
"description": "Specifies the category of account update to be performed after account opening. This field determines which account update scenario applies and which corresponding information object is required in the request. Each type represents a distinct account maintenance or compliance update operation."
},
"commission_info": {
"type": "object",
"description": "This object is applicable when the update type is COMMISSION_UPDATE.",
"properties": {
"commission_code": {
"type": "string",
"description": "Commission Code for account, determining the commission structure."
}
},
"required": [
"commission_code"
]
},
"identity_info": {
"type": "object",
"description": "This object is applicable when the update type is IDENTITY_UPDATE. This form is used to collect updated identification information for an existing account. It is required during account maintenance, periodic review, or compliance verification to ensure the accuracy and validity of identity records.",
"properties": {
"id_doc_type": {
"type": "string",
"description": "Type of identification document provided by the applicant. The value must be retrieved from the Master Data API where data_type = ID_DOC_TYPE."
},
"id_number": {
"type": "string",
"description": "Identification document number exactly as shown on the provided ID."
},
"id_expiry_date": {
"type": "string",
"description": "Expiration date of the identification document.",
"format": "yyyy-MM-dd"
},
"picture_front_doc_id": {
"type": "string",
"description": "Document ID referencing the uploaded image of the front side of the identification document."
},
"picture_back_doc_id": {
"type": "string",
"description": "Document ID referencing the uploaded image of the back side of the identification document."
}
},
"required": [
"id_doc_type",
"id_number",
"id_expiry_date",
"picture_front_doc_id",
"picture_back_doc_id"
]
},
"employment_info": {
"type": "object",
"description": "This object is applicable when the update type is EMPLOYMENT_UPDATE. Collects updated employment information required during account maintenance or compliance review.",
"properties": {
"employment_type": {
"type": "string",
"description": "Type of employment. Value must be obtained from the Master Data API with data_type = EMPLOYMENT_TYPE."
},
"company_name": {
"type": "string",
"description": "Name of the applicant current employer.",
"max_length": 128
},
"occupation": {
"type": "string",
"description": "Specific occupation under the employment type. Value must be obtained from the Master Data API with data_type = OCCUPATION."
},
"position": {
"type": "string",
"description": "Job position or title. Value must be obtained from the Master Data API with data_type = POSITION."
},
"years_employed": {
"type": "number",
"description": "Total duration (in years) the applicant has been employed with the current employer. Decimal values are allowed to represent partial years (e.g. 1.5)."
},
"employment_address": {
"type": "object",
"description": "Address of the applicant current employer.",
"properties": {
"country": {
"type": "string",
"description": "Employer address country. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"state": {
"type": "string",
"description": "Employer address state. The value must follow the ISO 3166-2 subdivision standard and include the country code prefix. Format: -"
},
"city": {
"type": "string",
"description": "Employer address city.",
"max_length": 256
},
"street_address": {
"type": "string",
"description": "Street address of the employer. Multiple lines are allowed.",
"max_length": 512
},
"postal_code": {
"type": "string",
"description": "Postal code of the employer address.",
"max_length": 80
},
"neighborhood_code": {
"type": "string",
"description": "Neighborhood or district code of the employer address, if applicable.",
"max_length": 128
},
"apartment_number": {
"type": "string",
"description": "Apartment number of the employer address, if applicable.",
"max_length": 128
},
"building_number": {
"type": "string",
"description": "Building number of the employer address, if applicable.",
"max_length": 128
}
},
"required": [
"country",
"state",
"city",
"street_address",
"postal_code",
"neighborhood_code",
"apartment_number",
"building_number"
]
}
},
"required": [
"employment_type",
"company_name",
"occupation",
"position",
"years_employed",
"employment_address"
]
},
"trusted_contact_info": {
"type": "object",
"description": "This object is applicable when the update type is TRUSTED_UPDATE. Collects or updates trusted contact information for an account, used for account protection, compliance review, or situations where the account holder cannot be contacted.",
"properties": {
"first_name": {
"type": "string",
"description": "First name of the trusted contact person."
},
"middle_name": {
"type": "string",
"description": "Middle name of the trusted contact person, if applicable."
},
"last_name": {
"type": "string",
"description": "Last name of the trusted contact person."
},
"phone_country": {
"type": "string",
"description": "Phone country. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"phone_number": {
"type": "string",
"description": "Primary contact phone number of the trusted contact person.",
"example": "+1-2025550124",
"max_length": 20
},
"relationship": {
"type": "string",
"description": "Relationship between the account holder and the trusted contact person.",
"max_length": 32
},
"trusted_address": {
"type": "object",
"description": "Residential or mailing address of the trusted contact person.",
"properties": {
"country": {
"type": "string",
"description": "Country of the trusted contact person address. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"state": {
"type": "string",
"description": "State or province of the trusted contact person address. The value must follow the ISO 3166-2 subdivision standard and include the country code prefix. Format: -"
},
"city": {
"type": "string",
"description": "City of the trusted contact person address.",
"max_length": 256
},
"street_address": {
"type": "string",
"description": "Street address of the trusted contact person. Multiple address lines are allowed.",
"max_length": 512
},
"postal_code": {
"type": "string",
"description": "Postal or ZIP code of the trusted contact person address.",
"max_length": 80
},
"neighborhood_code": {
"type": "string",
"description": "Neighborhood or district code of the trusted contact person address, if applicable.",
"max_length": 128
},
"apartment_number": {
"type": "string",
"description": "Apartment or unit number of the trusted contact person address, if applicable.",
"max_length": 128
},
"building_number": {
"type": "string",
"description": "Building number of the trusted contact person address, if applicable.",
"max_length": 128
}
},
"required": [
"country",
"state",
"city",
"street_address",
"postal_code",
"neighborhood_code"
]
}
},
"required": [
"first_name",
"last_name",
"phone_country",
"phone_number",
"relationship",
"trusted_address"
]
},
"email_address_info": {
"type": "object",
"description": "This object is applicable when the update type is EMAIL_ADDRESS_UPDATE. Collects or updates the primary email address associated with an account. This information is used for account communication, security notifications, and compliance-related correspondence.",
"properties": {
"email_address": {
"type": "string",
"description": "Email address",
"max_length": 256
}
},
"required": [
"email_address"
]
},
"address_info": {
"type": "object",
"description": "This object is applicable when the update type is ADDRESS_UPDATE. Collects or updates address information associated with an account, including residential and mailing addresses. This information is used for account administration, regulatory compliance, and official correspondence.",
"properties": {
"id_address": {
"type": "object",
"description": "Residential address of the account holder as recorded for identity verification and regulatory purposes.",
"properties": {
"country": {
"type": "string",
"description": "Country of residence. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"state": {
"type": "string",
"description": "State or province of residence. The value must follow the ISO 3166-2 subdivision standard and include the country code prefix. Format: -"
},
"city": {
"type": "string",
"description": "City of residence.",
"max_length": 256
},
"street_address": {
"type": "string",
"description": "Street address of the account holder residence. Multiple address lines are allowed.",
"max_length": 512
},
"postal_code": {
"type": "string",
"description": "Postal or ZIP code of the residential address.",
"max_length": 80
},
"neighborhood_code": {
"type": "string",
"description": "Neighborhood or district code of the id address, if applicable.",
"max_length": 128
},
"apartment_number": {
"type": "string",
"description": "Apartment number of the id address, if applicable.",
"max_length": 128
},
"building_number": {
"type": "string",
"description": "Building number of the id address, if applicable.",
"max_length": 128
}
},
"required": [
"country",
"state",
"city",
"street_address",
"postal_code",
"neighborhood_code",
"apartment_number",
"building_number"
]
},
"mail_address": {
"type": "object",
"description": "Mailing address used for receiving account-related correspondence, if different from the residential address.",
"properties": {
"country": {
"type": "string",
"description": "Mailing address country. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"state": {
"type": "string",
"description": "State or province of the mailing address. The value must follow the ISO 3166-2 subdivision standard and include the country code prefix. Format: -"
},
"city": {
"type": "string",
"description": "City of the mailing address.",
"max_length": 256
},
"street_address": {
"type": "string",
"description": "Street address of the mailing address. Multiple address lines are allowed.",
"max_length": 512
},
"postal_code": {
"type": "string",
"description": "Postal or ZIP code of the mailing address.",
"max_length": 80
},
"neighborhood_code": {
"type": "string",
"description": "Neighborhood or district code of the mailing address.",
"max_length": 128
},
"apartment_number": {
"type": "string",
"description": "Apartment number of the mailing address.",
"max_length": 128
},
"building_number": {
"type": "string",
"description": "Building number of the mailing address.",
"max_length": 128
}
},
"required": [
"country",
"state",
"city",
"street_address",
"postal_code",
"neighborhood_code",
"apartment_number",
"building_number"
]
}
},
"required": [
"id_address",
"mail_address"
]
},
"phone_number_info": {
"type": "object",
"description": "This object is applicable when the update type is PHONE_NUMBER_UPDATE. Collects or updates the primary phone number associated with an account, used for account communication, security verification, and regulatory notifications.",
"properties": {
"phone_country": {
"type": "string",
"description": "Phone country. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"phone_number": {
"type": "string",
"description": "Primary contact phone number associated with the account, in international format (E.164). Used for account notifications, verification, and security-related communications.",
"example": "+1-2025550123",
"max_length": 20
}
},
"required": [
"phone_country",
"phone_number"
]
},
"politically_exposed_info": {
"type": "object",
"description": "This object is applicable when the update type is PEP_UPDATE. Collects or updates Politically Exposed Person (PEP) information for an account. This information is used for compliance review, enhanced due diligence (EDD), and regulatory reporting.",
"properties": {
"is_politically_exposed": {
"type": "boolean",
"description": "Indicates whether the account holder or any close associate or immediate family member is a Politically Exposed Person (PEP). If true, the politically_exposed_info object must be provided with detailed disclosure information. Please note: PEP accounts are currently not supported. Any request submitted with is_politically_exposed = true will be rejected and a failure response will be returned."
},
"politically_exposed_info": {
"type": "object",
"description": "Detail information about Politically Exposed Person (PEP) associated with the account holder.",
"properties": {
"pep_organization": {
"type": "string",
"description": "Name of the related political organization.",
"max_length": 256
},
"immediate_family": {
"type": "array",
"description": "Name of family members, including former spouses.",
"items": {
"type": "string",
"description": ""
}
}
},
"required": [
"pep_organization",
"immediate_family"
]
}
},
"required": [
"is_politically_exposed"
]
},
"company_control_info": {
"type": "object",
"description": "This object is applicable when the update type is COMPANY_CONTROL_UPDATE. Collects or updates information about the applicant status as a control person of a public company. This information is used for compliance review, enhanced due diligence (EDD), and regulatory reporting.",
"properties": {
"is_company_control_person": {
"type": "boolean",
"description": "Indicates whether the applicant is a control person of a public company. If true, `public_company_infos` must be provided with details of the companies controlled."
},
"public_company_infos": {
"type": "array",
"description": "List of public companies controlled by the applicant. Each item must include the company stock symbol.",
"items": {
"type": "object",
"description": "",
"properties": {
"symbol": {
"type": "string",
"description": "Stock symbol of the public company controlled by the applicant, as listed on the exchange."
}
},
"required": [
"symbol"
]
}
}
},
"required": [
"is_company_control_person"
]
},
"disclosure_info": {
"type": "object",
"description": "This object is applicable when the update type is DISCLOSURE_UPDATE. Collects or updates the applicant regulatory and compliance-related affiliations or disclosures. This form is used for compliance review, enhanced due diligence (EDD), and regulatory reporting, and may include multiple types of information beyond exchange or FINRA affiliations.",
"properties": {
"brokerage_disclosure_info": {
"type": "object",
"description": "Brokerage disclosure info",
"properties": {
"is_exchange_or_finra_affiliated": {
"type": "boolean",
"description": "Indicates whether the applicant is employed by, or directly associated with, an exchange or a FINRA member firm. If true, exchange_affiliations details must be provided."
},
"exchange_affiliations": {
"type": "array",
"description": "List of the applicant affiliations with exchanges or FINRA member firms. Required if is_exchange_or_finra_affiliated is true.",
"items": {
"type": "object",
"description": "",
"properties": {
"company_name": {
"type": "string",
"description": "Name of the exchange or FINRA member firm the applicant is affiliated with.",
"max_length": 128
},
"country": {
"type": "string",
"description": "Country of the affiliated exchange or FINRA firm. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"state": {
"type": "string",
"description": "State or province of the affiliated exchange or FINRA firm. Value must be obtained from the Master Data API with data_type = STATE."
},
"city": {
"type": "string",
"description": "City of the affiliated exchange or FINRA firm.",
"max_length": 256
},
"street_address": {
"type": "string",
"description": "Street address of the affiliated exchange or FINRA firm. Multiple lines are allowed.",
"max_length": 512
},
"postal_code": {
"type": "string",
"description": "Postal or ZIP code of the affiliated exchange or FINRA firm.",
"max_length": 80
}
},
"required": [
"company_name",
"country",
"state",
"city",
"street_address",
"postal_code"
]
}
}
},
"required": [
"is_exchange_or_finra_affiliated"
]
}
},
"required": [
"brokerage_disclosure_info"
]
},
"dependent_info": {
"type": "object",
"description": "This object is applicable when the update type is DEPENDENT_UPDATE. Collects or updates the number of dependents associated with an account holder. This information is used for account maintenance, compliance review, and regulatory reporting purposes.",
"properties": {
"num_dependents": {
"type": "number",
"description": "Number of dependents financially or legally associated with the account holder."
}
},
"required": [
"num_dependents"
]
},
"citizenship_info": {
"type": "object",
"description": "This object is applicable when the update type is CITIZENSHIP_UPDATE. Collects or updates the country of citizenship for an account holder. This information is used for account maintenance, compliance review, and regulatory reporting.",
"properties": {
"country_of_citizenship": {
"type": "string",
"description": "Country of citizenship of the account holder. The value must be retrieved from the Master Data API with data_type = COUNTRY."
}
},
"required": [
"country_of_citizenship"
]
},
"gender_info": {
"type": "object",
"description": "This object is applicable when the update type is GENDER_UPDATE. Collects or updates the gender of an account holder. This information is used for account maintenance, compliance review, and regulatory reporting.",
"properties": {
"gender": {
"type": "string",
"description": "Gender of the account holder. Allowed values: F (Female), M (Male)."
}
},
"required": [
"gender"
]
},
"marital_info": {
"type": "object",
"description": "This object is applicable when the update type is MARITAL_UPDATE. Collects or updates the marital status of an account holder. This information is used for account maintenance, compliance review, and regulatory reporting.",
"properties": {
"marital_status": {
"type": "string",
"description": "Marital status of the account holder. Value must be obtained from the Master Data API with data_type = MARITAL_STATUS."
}
},
"required": [
"marital_status"
]
},
"financial_investment_info": {
"type": "object",
"description": "This object is applicable when the update type is FINANCIAL_INVESTMENT_UPDATE. Collects or updates the investment profile and financial information of an account holder. This information is used for account maintenance, risk assessment, and regulatory compliance.",
"properties": {
"financial_info": {
"type": "object",
"description": "Financial information of the account holder.",
"properties": {
"liquidity_needs": {
"type": "string",
"description": "Indicates the client liquidity needs or preference for cash accessibility. Value must be obtained from the Master Data API with data_type = LIQUIDITY_NEEDS."
},
"annual_income": {
"type": "string",
"description": "Represents the client annual income. Value must be obtained from the Master Data API with data_type = ANNUAL_INCOME."
},
"total_net_worth": {
"type": "string",
"description": "Represents the client total net worth in USD. Value must be obtained from the Master Data API with data_type = TOTAL_NET_WORTH."
},
"liquid_net_worth": {
"type": "string",
"description": "Represents the client liquid net worth (USD), including cash and easily marketable assets. Value must be obtained from the Master Data API with data_type = LIQUID_NET_WORTH."
}
},
"required": [
"liquidity_needs",
"annual_income",
"total_net_worth",
"liquid_net_worth"
]
},
"event_contract_investment_info": {
"type": "object",
"description": "Event contract account investment info",
"properties": {
"investment_experience": {
"type": "string",
"description": "Event contract investment experience. Value must be obtained from the Master Data API with data_type = INVESTMENT_EXPERIENCE."
},
"investment_knowledge": {
"type": "string",
"description": "Event contract investment knowledge. Value must be obtained from the Master Data API with data_type = INVESTMENT_KNOWLEDGE_V2."
},
"trade_per_year": {
"type": "string",
"description": "Event contract trade per year. Value must be obtained from the Master Data API with data_type = TRADE_PER_YEAR."
}
},
"required": [
"investment_experience",
"investment_knowledge",
"trade_per_year"
]
},
"brokerage_investment_info": {
"type": "object",
"description": "Brokerage account investment info",
"properties": {
"investment_knowledge": {
"type": "string",
"description": "Investment knowledge. Value must be obtained from the Master Data API with data_type = INVESTMENT_KNOWLEDGE."
},
"investment_objective": {
"type": "string",
"description": "Investment objective. Value must be obtained from the Master Data API with data_type = INVESTMENT_OBJECTIVE."
},
"time_horizon": {
"type": "string",
"description": "Time horizon. Value must be obtained from the Master Data API with data_type = TIME_HORIZON."
}
},
"required": [
"investment_knowledge",
"investment_objective",
"time_horizon"
]
}
}
}
},
"required": [
"type"
]
}
}
},
"description": "Account Info Update Form",
"title": "AccountUpdateForm"
}
}
},
"description": "Account Info Update Submit Request",
"title": "AccountUpdateSubmitRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"required": [
"account_id",
"client_request_id"
],
"type": "object",
"properties": {
"client_request_id": {
"type": "string",
"description": "Unique client-generated identifier used for request tracking, idempotency and audit purposes.",
"example": "4F5A13B5FDFD43D29C7A3A856B2458A1"
},
"account_id": {
"type": "string",
"description": "System-generated unique identifier assigned to the account application record.",
"example": "943a9802f6c14983b3b4755c69c01717"
}
},
"description": "Account Update Response",
"title": "AccountUpdateResult"
}
}
}
},
"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": "123e4567e89b12d3a456426614174000",
"account_id": "943a9802f6c14983b3b4755c69c01717",
"forms": [
{
"form_info": {
"form_code": "UPDATE_ACCOUNT_FORM",
"version": "1.0"
},
"json_data": {
"type": "object",
"description": "This form is used to submit post-onboarding account update requests for an existing account. It serves as a unified entry point for multiple account maintenance and compliance-related update scenarios after the account has been successfully opened. The specific update scenario is determined by the `type` field. Based on the selected type, the corresponding update information object must be provided. This form is commonly used for periodic reviews, regulatory compliance verification, risk control follow-ups, and other account data maintenance processes to ensure that account records remain accurate, valid, and up to date.",
"form_code": "ACCOUNT_UPDATE_FORM",
"properties": {
"type": {
"type": "string",
"description": "Specifies the category of account update to be performed after account opening. This field determines which account update scenario applies and which corresponding information object is required in the request. Each type represents a distinct account maintenance or compliance update operation."
},
"commission_info": {
"type": "object",
"description": "This object is applicable when the update type is COMMISSION_UPDATE.",
"properties": {
"commission_code": {
"type": "string",
"description": "Commission Code for account, determining the commission structure."
}
},
"required": [
"commission_code"
]
},
"identity_info": {
"type": "object",
"description": "This object is applicable when the update type is IDENTITY_UPDATE. This form is used to collect updated identification information for an existing account. It is required during account maintenance, periodic review, or compliance verification to ensure the accuracy and validity of identity records.",
"properties": {
"id_doc_type": {
"type": "string",
"description": "Type of identification document provided by the applicant. The value must be retrieved from the Master Data API where data_type = ID_DOC_TYPE."
},
"id_number": {
"type": "string",
"description": "Identification document number exactly as shown on the provided ID."
},
"id_expiry_date": {
"type": "string",
"description": "Expiration date of the identification document.",
"format": "yyyy-MM-dd"
},
"picture_front_doc_id": {
"type": "string",
"description": "Document ID referencing the uploaded image of the front side of the identification document."
},
"picture_back_doc_id": {
"type": "string",
"description": "Document ID referencing the uploaded image of the back side of the identification document."
}
},
"required": [
"id_doc_type",
"id_number",
"id_expiry_date",
"picture_front_doc_id",
"picture_back_doc_id"
]
},
"employment_info": {
"type": "object",
"description": "This object is applicable when the update type is EMPLOYMENT_UPDATE. Collects updated employment information required during account maintenance or compliance review.",
"properties": {
"employment_type": {
"type": "string",
"description": "Type of employment. Value must be obtained from the Master Data API with data_type = EMPLOYMENT_TYPE."
},
"company_name": {
"type": "string",
"description": "Name of the applicant current employer.",
"max_length": 128
},
"occupation": {
"type": "string",
"description": "Specific occupation under the employment type. Value must be obtained from the Master Data API with data_type = OCCUPATION."
},
"position": {
"type": "string",
"description": "Job position or title. Value must be obtained from the Master Data API with data_type = POSITION."
},
"years_employed": {
"type": "number",
"description": "Total duration (in years) the applicant has been employed with the current employer. Decimal values are allowed to represent partial years (e.g. 1.5)."
},
"employment_address": {
"type": "object",
"description": "Address of the applicant current employer.",
"properties": {
"country": {
"type": "string",
"description": "Employer address country. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"state": {
"type": "string",
"description": "Employer address state. The value must follow the ISO 3166-2 subdivision standard and include the country code prefix. Format: -"
},
"city": {
"type": "string",
"description": "Employer address city.",
"max_length": 256
},
"street_address": {
"type": "string",
"description": "Street address of the employer. Multiple lines are allowed.",
"max_length": 512
},
"postal_code": {
"type": "string",
"description": "Postal code of the employer address.",
"max_length": 80
},
"neighborhood_code": {
"type": "string",
"description": "Neighborhood or district code of the employer address, if applicable.",
"max_length": 128
},
"apartment_number": {
"type": "string",
"description": "Apartment number of the employer address, if applicable.",
"max_length": 128
},
"building_number": {
"type": "string",
"description": "Building number of the employer address, if applicable.",
"max_length": 128
}
},
"required": [
"country",
"state",
"city",
"street_address",
"postal_code",
"neighborhood_code",
"apartment_number",
"building_number"
]
}
},
"required": [
"employment_type",
"company_name",
"occupation",
"position",
"years_employed",
"employment_address"
]
},
"trusted_contact_info": {
"type": "object",
"description": "This object is applicable when the update type is TRUSTED_UPDATE. Collects or updates trusted contact information for an account, used for account protection, compliance review, or situations where the account holder cannot be contacted.",
"properties": {
"first_name": {
"type": "string",
"description": "First name of the trusted contact person."
},
"middle_name": {
"type": "string",
"description": "Middle name of the trusted contact person, if applicable."
},
"last_name": {
"type": "string",
"description": "Last name of the trusted contact person."
},
"phone_country": {
"type": "string",
"description": "Phone country. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"phone_number": {
"type": "string",
"description": "Primary contact phone number of the trusted contact person.",
"example": "+1-2025550124",
"max_length": 20
},
"relationship": {
"type": "string",
"description": "Relationship between the account holder and the trusted contact person.",
"max_length": 32
},
"trusted_address": {
"type": "object",
"description": "Residential or mailing address of the trusted contact person.",
"properties": {
"country": {
"type": "string",
"description": "Country of the trusted contact person address. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"state": {
"type": "string",
"description": "State or province of the trusted contact person address. The value must follow the ISO 3166-2 subdivision standard and include the country code prefix. Format: -"
},
"city": {
"type": "string",
"description": "City of the trusted contact person address.",
"max_length": 256
},
"street_address": {
"type": "string",
"description": "Street address of the trusted contact person. Multiple address lines are allowed.",
"max_length": 512
},
"postal_code": {
"type": "string",
"description": "Postal or ZIP code of the trusted contact person address.",
"max_length": 80
},
"neighborhood_code": {
"type": "string",
"description": "Neighborhood or district code of the trusted contact person address, if applicable.",
"max_length": 128
},
"apartment_number": {
"type": "string",
"description": "Apartment or unit number of the trusted contact person address, if applicable.",
"max_length": 128
},
"building_number": {
"type": "string",
"description": "Building number of the trusted contact person address, if applicable.",
"max_length": 128
}
},
"required": [
"country",
"state",
"city",
"street_address",
"postal_code",
"neighborhood_code"
]
}
},
"required": [
"first_name",
"last_name",
"phone_country",
"phone_number",
"relationship",
"trusted_address"
]
},
"email_address_info": {
"type": "object",
"description": "This object is applicable when the update type is EMAIL_ADDRESS_UPDATE. Collects or updates the primary email address associated with an account. This information is used for account communication, security notifications, and compliance-related correspondence.",
"properties": {
"email_address": {
"type": "string",
"description": "Email address",
"max_length": 256
}
},
"required": [
"email_address"
]
},
"address_info": {
"type": "object",
"description": "This object is applicable when the update type is ADDRESS_UPDATE. Collects or updates address information associated with an account, including residential and mailing addresses. This information is used for account administration, regulatory compliance, and official correspondence.",
"properties": {
"id_address": {
"type": "object",
"description": "Residential address of the account holder as recorded for identity verification and regulatory purposes.",
"properties": {
"country": {
"type": "string",
"description": "Country of residence. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"state": {
"type": "string",
"description": "State or province of residence. The value must follow the ISO 3166-2 subdivision standard and include the country code prefix. Format: -"
},
"city": {
"type": "string",
"description": "City of residence.",
"max_length": 256
},
"street_address": {
"type": "string",
"description": "Street address of the account holder residence. Multiple address lines are allowed.",
"max_length": 512
},
"postal_code": {
"type": "string",
"description": "Postal or ZIP code of the residential address.",
"max_length": 80
},
"neighborhood_code": {
"type": "string",
"description": "Neighborhood or district code of the id address, if applicable.",
"max_length": 128
},
"apartment_number": {
"type": "string",
"description": "Apartment number of the id address, if applicable.",
"max_length": 128
},
"building_number": {
"type": "string",
"description": "Building number of the id address, if applicable.",
"max_length": 128
}
},
"required": [
"country",
"state",
"city",
"street_address",
"postal_code",
"neighborhood_code",
"apartment_number",
"building_number"
]
},
"mail_address": {
"type": "object",
"description": "Mailing address used for receiving account-related correspondence, if different from the residential address.",
"properties": {
"country": {
"type": "string",
"description": "Mailing address country. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"state": {
"type": "string",
"description": "State or province of the mailing address. The value must follow the ISO 3166-2 subdivision standard and include the country code prefix. Format: -"
},
"city": {
"type": "string",
"description": "City of the mailing address.",
"max_length": 256
},
"street_address": {
"type": "string",
"description": "Street address of the mailing address. Multiple address lines are allowed.",
"max_length": 512
},
"postal_code": {
"type": "string",
"description": "Postal or ZIP code of the mailing address.",
"max_length": 80
},
"neighborhood_code": {
"type": "string",
"description": "Neighborhood or district code of the mailing address.",
"max_length": 128
},
"apartment_number": {
"type": "string",
"description": "Apartment number of the mailing address.",
"max_length": 128
},
"building_number": {
"type": "string",
"description": "Building number of the mailing address.",
"max_length": 128
}
},
"required": [
"country",
"state",
"city",
"street_address",
"postal_code",
"neighborhood_code",
"apartment_number",
"building_number"
]
}
},
"required": [
"id_address",
"mail_address"
]
},
"phone_number_info": {
"type": "object",
"description": "This object is applicable when the update type is PHONE_NUMBER_UPDATE. Collects or updates the primary phone number associated with an account, used for account communication, security verification, and regulatory notifications.",
"properties": {
"phone_country": {
"type": "string",
"description": "Phone country. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"phone_number": {
"type": "string",
"description": "Primary contact phone number associated with the account, in international format (E.164). Used for account notifications, verification, and security-related communications.",
"example": "+1-2025550123",
"max_length": 20
}
},
"required": [
"phone_country",
"phone_number"
]
},
"politically_exposed_info": {
"type": "object",
"description": "This object is applicable when the update type is PEP_UPDATE. Collects or updates Politically Exposed Person (PEP) information for an account. This information is used for compliance review, enhanced due diligence (EDD), and regulatory reporting.",
"properties": {
"is_politically_exposed": {
"type": "boolean",
"description": "Indicates whether the account holder or any close associate or immediate family member is a Politically Exposed Person (PEP). If true, the politically_exposed_info object must be provided with detailed disclosure information. Please note: PEP accounts are currently not supported. Any request submitted with is_politically_exposed = true will be rejected and a failure response will be returned."
},
"politically_exposed_info": {
"type": "object",
"description": "Detail information about Politically Exposed Person (PEP) associated with the account holder.",
"properties": {
"pep_organization": {
"type": "string",
"description": "Name of the related political organization.",
"max_length": 256
},
"immediate_family": {
"type": "array",
"description": "Name of family members, including former spouses.",
"items": {
"type": "string",
"description": ""
}
}
},
"required": [
"pep_organization",
"immediate_family"
]
}
},
"required": [
"is_politically_exposed"
]
},
"company_control_info": {
"type": "object",
"description": "This object is applicable when the update type is COMPANY_CONTROL_UPDATE. Collects or updates information about the applicant status as a control person of a public company. This information is used for compliance review, enhanced due diligence (EDD), and regulatory reporting.",
"properties": {
"is_company_control_person": {
"type": "boolean",
"description": "Indicates whether the applicant is a control person of a public company. If true, `public_company_infos` must be provided with details of the companies controlled."
},
"public_company_infos": {
"type": "array",
"description": "List of public companies controlled by the applicant. Each item must include the company stock symbol.",
"items": {
"type": "object",
"description": "",
"properties": {
"symbol": {
"type": "string",
"description": "Stock symbol of the public company controlled by the applicant, as listed on the exchange."
}
},
"required": [
"symbol"
]
}
}
},
"required": [
"is_company_control_person"
]
},
"disclosure_info": {
"type": "object",
"description": "This object is applicable when the update type is DISCLOSURE_UPDATE. Collects or updates the applicant regulatory and compliance-related affiliations or disclosures. This form is used for compliance review, enhanced due diligence (EDD), and regulatory reporting, and may include multiple types of information beyond exchange or FINRA affiliations.",
"properties": {
"brokerage_disclosure_info": {
"type": "object",
"description": "Brokerage disclosure info",
"properties": {
"is_exchange_or_finra_affiliated": {
"type": "boolean",
"description": "Indicates whether the applicant is employed by, or directly associated with, an exchange or a FINRA member firm. If true, exchange_affiliations details must be provided."
},
"exchange_affiliations": {
"type": "array",
"description": "List of the applicant affiliations with exchanges or FINRA member firms. Required if is_exchange_or_finra_affiliated is true.",
"items": {
"type": "object",
"description": "",
"properties": {
"company_name": {
"type": "string",
"description": "Name of the exchange or FINRA member firm the applicant is affiliated with.",
"max_length": 128
},
"country": {
"type": "string",
"description": "Country of the affiliated exchange or FINRA firm. The value must be a valid ISO 3166-1 alpha-3 country code in uppercase format (3-letter code)."
},
"state": {
"type": "string",
"description": "State or province of the affiliated exchange or FINRA firm. Value must be obtained from the Master Data API with data_type = STATE."
},
"city": {
"type": "string",
"description": "City of the affiliated exchange or FINRA firm.",
"max_length": 256
},
"street_address": {
"type": "string",
"description": "Street address of the affiliated exchange or FINRA firm. Multiple lines are allowed.",
"max_length": 512
},
"postal_code": {
"type": "string",
"description": "Postal or ZIP code of the affiliated exchange or FINRA firm.",
"max_length": 80
}
},
"required": [
"company_name",
"country",
"state",
"city",
"street_address",
"postal_code"
]
}
}
},
"required": [
"is_exchange_or_finra_affiliated"
]
}
},
"required": [
"brokerage_disclosure_info"
]
},
"dependent_info": {
"type": "object",
"description": "This object is applicable when the update type is DEPENDENT_UPDATE. Collects or updates the number of dependents associated with an account holder. This information is used for account maintenance, compliance review, and regulatory reporting purposes.",
"properties": {
"num_dependents": {
"type": "number",
"description": "Number of dependents financially or legally associated with the account holder."
}
},
"required": [
"num_dependents"
]
},
"citizenship_info": {
"type": "object",
"description": "This object is applicable when the update type is CITIZENSHIP_UPDATE. Collects or updates the country of citizenship for an account holder. This information is used for account maintenance, compliance review, and regulatory reporting.",
"properties": {
"country_of_citizenship": {
"type": "string",
"description": "Country of citizenship of the account holder. The value must be retrieved from the Master Data API with data_type = COUNTRY."
}
},
"required": [
"country_of_citizenship"
]
},
"gender_info": {
"type": "object",
"description": "This object is applicable when the update type is GENDER_UPDATE. Collects or updates the gender of an account holder. This information is used for account maintenance, compliance review, and regulatory reporting.",
"properties": {
"gender": {
"type": "string",
"description": "Gender of the account holder. Allowed values: F (Female), M (Male)."
}
},
"required": [
"gender"
]
},
"marital_info": {
"type": "object",
"description": "This object is applicable when the update type is MARITAL_UPDATE. Collects or updates the marital status of an account holder. This information is used for account maintenance, compliance review, and regulatory reporting.",
"properties": {
"marital_status": {
"type": "string",
"description": "Marital status of the account holder. Value must be obtained from the Master Data API with data_type = MARITAL_STATUS."
}
},
"required": [
"marital_status"
]
},
"financial_investment_info": {
"type": "object",
"description": "This object is applicable when the update type is FINANCIAL_INVESTMENT_UPDATE. Collects or updates the investment profile and financial information of an account holder. This information is used for account maintenance, risk assessment, and regulatory compliance.",
"properties": {
"financial_info": {
"type": "object",
"description": "Financial information of the account holder.",
"properties": {
"liquidity_needs": {
"type": "string",
"description": "Indicates the client liquidity needs or preference for cash accessibility. Value must be obtained from the Master Data API with data_type = LIQUIDITY_NEEDS."
},
"annual_income": {
"type": "string",
"description": "Represents the client annual income. Value must be obtained from the Master Data API with data_type = ANNUAL_INCOME."
},
"total_net_worth": {
"type": "string",
"description": "Represents the client total net worth in USD. Value must be obtained from the Master Data API with data_type = TOTAL_NET_WORTH."
},
"liquid_net_worth": {
"type": "string",
"description": "Represents the client liquid net worth (USD), including cash and easily marketable assets. Value must be obtained from the Master Data API with data_type = LIQUID_NET_WORTH."
}
},
"required": [
"liquidity_needs",
"annual_income",
"total_net_worth",
"liquid_net_worth"
]
},
"event_contract_investment_info": {
"type": "object",
"description": "Event contract account investment info",
"properties": {
"investment_experience": {
"type": "string",
"description": "Event contract investment experience. Value must be obtained from the Master Data API with data_type = INVESTMENT_EXPERIENCE."
},
"investment_knowledge": {
"type": "string",
"description": "Event contract investment knowledge. Value must be obtained from the Master Data API with data_type = INVESTMENT_KNOWLEDGE_V2."
},
"trade_per_year": {
"type": "string",
"description": "Event contract trade per year. Value must be obtained from the Master Data API with data_type = TRADE_PER_YEAR."
}
},
"required": [
"investment_experience",
"investment_knowledge",
"trade_per_year"
]
},
"brokerage_investment_info": {
"type": "object",
"description": "Brokerage account investment info",
"properties": {
"investment_knowledge": {
"type": "string",
"description": "Investment knowledge. Value must be obtained from the Master Data API with data_type = INVESTMENT_KNOWLEDGE."
},
"investment_objective": {
"type": "string",
"description": "Investment objective. Value must be obtained from the Master Data API with data_type = INVESTMENT_OBJECTIVE."
},
"time_horizon": {
"type": "string",
"description": "Time horizon. Value must be obtained from the Master Data API with data_type = TIME_HORIZON."
}
},
"required": [
"investment_knowledge",
"investment_objective",
"time_horizon"
]
}
}
}
},
"required": [
"type"
]
}
}
]
},
"postman": {
"name": "Update Account",
"description": {
"content": "Submit a request to update an existing account. This API only updates the fields submitted in the forms data. Any attributes not included in the request will remain unchanged.
Related Event Notifications:
Please refer to the Event Push API documentation: [Account Events](../fd-events/account-events)",
"type": "text/plain"
},
"url": {
"path": [
"broker",
"accounts",
"update"
],
"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"
}
}
}
}
}
```