Skip to main content

​
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

FieldTypeRequiredDescription
email_addressstring✅Primary email address
phone_numberstringPhone with country code (e.g. +15125550100)
street_addressstring[]Street address lines
unitstringApartment, suite, or unit number
citystring✅City
statestring✅2-letter state code (e.g. TX)
postal_codestring✅ZIP code (5 or 9 digits)
countrystringISO 2-letter country code. Defaults to US

​
identity object

FieldTypeRequiredDescription
given_namestring✅Legal first name
middle_namestringMiddle name or initial
family_namestring✅Legal last name
date_of_birthstring✅Date of birth in YYYY-MM-DD format
tax_idstring✅SSN (US residents) or EIN. 9–11 characters, dashes optional.
tax_id_typestringDefaults to US_SSN. Other values: US_EIN
country_of_citizenshipstringISO country code. Defaults to US
country_of_birthstringISO country code of birth country
country_of_tax_residencestringISO country code for tax residence. Defaults to US
funding_sourcestring[]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 options_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/capital_preservation/other), annual_income_range, net_worth_range, liquid_net_worth_range. Optional: liquidity_needs, time_horizon (short/average/long), years_trading_stocks, years_trading_options, stock_experience, options_experience, income_source, funds_source, investment_plan.

​
trading_configurations object (optional)

options_level (0=none, 1=covered calls, 2=spreads, 3=full); margin_enabled (requires margin_agreement).

​
Other optional top-level fields

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

​
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-0001", "tax_id_type": "US_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": { "options_level": 0, "margin_enabled": false },
  "dividend_reinvestment": true,
  "corr_metadata": "internal-user-id-98765"
}

​
Response

On success, returns 201 Created with the full AccountResponse object including the generated id and initial status. 
{
  "id": "b3f2c9a1-4d5e-4a2f-8b3c-1e2d3f4a5b6c",
  "account_number": "ACC123456789",
  "status": "SUBMITTED",
  "kyc_status": "SUBMITTED",
  "currency": "USD",
  "last_equity": "0.00",
  "created_at": "2025-06-01T12:00:05Z",
  "account_type": "individual",
  "enabled_assets": ["equity"]
}
Note: Newly created accounts start in SUBMITTED status. In the sandbox with SSN suffix 0001, KYC completes rapidly and transitions to ACTIVE. In production, KYC processing typically completes in seconds to minutes, but some accounts require manual review.

​
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

ErrorCause
MISSING_REQUIRED_FIELD: contact.email_addressEmail address omitted from contact
MISSING_REQUIRED_FIELD: identity.tax_idSSN omitted from identity
VALIDATION_ERROR: identity.date_of_birthDate not in YYYY-MM-DD format
MISSING_REQUIRED_FIELD: agreementsNo agreements array provided
VALIDATION_ERROR: agreements[0].signed_atTimestamp 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