Sign in

v1

latestOpenAPI 3.0.02026-07-26166415635.8 KB
Accounts

Create an Account

Submit an account application with KYC information. This will create a trading account for the end user. The account status may or may not be ACTIVE immediately and you will receive account status updates on the event API.

Multi-Live Accounts (MLA): To open an additional account for an existing account holder, supply primary_account_holder_id at the top level instead of contact/identity data. In that case, supplying contact or identity returns HTTP 400. Only account_type of trading and ira are supported via this flow.

post/v1/accounts

Request body

account_sub_type'traditional' | 'roth'

IRA Account only

Possible values are:

  • traditional
  • roth
account_type'trading' | 'custodial' | 'donor_advised' | 'ira'

Possible values are:

  • trading
  • custodial
  • donor_advised
  • ira
allow_instant_achboolean

Determines whether the account will be enabled for Instant ACH by the partner. Defaults to false if not provided.

enabled_assetsAssetClass[]

Will default to us_equity. Alpaca has the ability to update the default value upon request.

investment_objective'generate_income' | 'preserve_wealth' | 'market_speculation' | 'growth' | 'balance_preserve_wealth_with_growth'

The user's investment objective. This field should be used instead of the deprecated investment_objective under identity.

investment_time_horizon'less_than_1_year' | '1_to_2_years' | '3_to_5_years' | '6_to_10_years' | 'more_than_10_years'

The expected period of time the user plan to invest to achieve his/her financial goal(s). This field should be used instead of the deprecated investment_time_horizon under identity.

liquidity_needs'very_important' | 'important' | 'somewhat_important' | 'does_not_matter'

The user's ability to quickly and easily convert to cash all or a portion of the investments in this account without experiencing significant loss in value. This field should be used instead of the deprecated liquidity_needs under identity.

primary_account_holder_idstring uuid

UUID of an existing account holder (party) to use as the primary account holder for the new account. Used to open additional accounts under the Multi-Live Accounts (MLA) flow.

When present:

  • contact and identity must be omitted (returns HTTP 400 otherwise).
  • agreements must still be supplied (e.g. customer_agreement for trading; customer_agreement and etc_agreement for IRA).
  • Only account_type values of trading and ira are supported.
risk_tolerance'conservative' | 'moderate' | 'significant_risk'

The user's investment risk tolerance. This field should be used instead of the deprecated risk_tolerance under identity.

Example request

{
  "account_sub_type": "traditional",
  "account_type": "trading",
  "agreements": [
    {
      "agreement": "customer_agreement",
      "ip_address": "185.13.21.99",
      "signed_at": "2019-09-11T18:09:33Z"
    }
  ],
  "beneficiaries": [
    {
      "date_of_birth": "1970-01-01",
      "family_name": "Doe",
      "given_name": "Jane",
      "middle_name": "P",
      "relationship": "spouse",
      "share_pct": "100",
      "tax_id": "xxx-xx-xxxx",
      "tax_id_type": "USA_SSN",
      "type": "primary"
    }
  ],
  "cash_interest": {
    "USD": {
      "apr_tier_name": "gold",
      "status": "ACTIVE"
    }
  },
  "contact": {
    "city": "San Mateo",
    "country": "USA",
    "email_address": "john.doe@example.com",
    "phone_number": "+15556667788",
    "postal_code": "94401",
    "state": "CA",
    "street_address": [
      "20 N San Mateo Dr"
    ]
  },
  "disclosures": {
    "immediate_family_exposed": false,
    "is_affiliated_exchange_or_finra": false,
    "is_control_person": false,
    "is_politically_exposed": false
  },
  "documents": [
    {
      "content": "/9j/Cg==",
      "document_sub_type": "passport",
      "document_type": "identity_verification",
      "mime_type": "image/jpeg"
    }
  ],
  "fpsl": {
    "US": {
      "tier_id": "61e69015-8549-4bfd-b9c3-01e75843f47d"
    }
  },
  "identity": {
    "country_of_birth": "AUS",
    "country_of_citizenship": "AUS",
    "country_of_tax_residence": "USA",
    "date_of_birth": "1990-01-01",
    "family_name": "Doe",
    "funding_source": [
      "employment_income"
    ],
    "given_name": "John",
    "tax_id": "666-55-4321",
    "tax_id_type": "USA_SSN"
  },
  "trusted_contact": {
    "email_address": "jane.doe@example.com",
    "family_name": "Doe",
    "given_name": "Jane"
  }
}

Response

OK

account_numberstring nullable required

A human-readable account number that can be shown to the end user

account_type'trading' | 'custodial' | 'donor_advised' | 'ira'

Possible values are:

  • trading
  • custodial
  • donor_advised
  • ira
allow_instant_achboolean

Determines whether the account is enabled for Instant ACH by the partner.

created_atstring date-time required

Timestamp (RFC3339) of account creation.

crypto_status'INACTIVE' | 'ONBOARDING' | 'SUBMITTED' | 'SUBMISSION_FAILED' | 'ACTION_REQUIRED' | 'ACCOUNT_UPDATED' | 'APPROVAL_PENDING' | 'APPROVED' | 'REJECTED' | 'ACTIVE' | 'ACCOUNT_CLOSED'

Designates the current status of this account

Possible Values:

  • INACTIVE Account not set to trade given asset.
  • ONBOARDING An application is expected for this user, but has not been submitted yet.
  • SUBMITTED The application has been submitted and is being processed.
  • SUBMISSION_FAILED Used to display if failure on submission
  • ACTION_REQUIRED The application requires manual action.
  • ACCOUNT_UPDATED Used to display when Account has been modified by user
  • APPROVAL_PENDING Initial value. The application approval process is in progress.
  • APPROVED The account application has been approved, and waiting to be ACTIVE
  • REJECTED The account application is rejected for some reason
  • ACTIVE The account is fully active. Trading and funding are processed under this status.
  • ACCOUNT_CLOSED The account is closed.
currencystring required

"USD" // US Dollar "JPY" // Japanese Yen "EUR" // Euro "CAD" // Canadian Dollar "GBP" // British Pound Sterling "CHF" // Swiss Franc "TRY" // Turkish Lira "AUD" // Australian Dollar "CZK" // Czech Koruna "SEK" // Swedish Krona "DKK" // Danish Krone "SGD" // Singapore Dollar "HKD" // Hong Kong Dollar "HUF" // Hungarian Forint "NZD" // New Zealand Dollar "NOK" // Norwegian Krone "PLN" // Poland Złoty

enabled_assetsAssetClass[]

Assets the user has enabled and is able to trade once status and/or crypto_status are ACTIVE

idstring uuid required

UUID that identifies the account for later reference

instant_ach_blockedboolean

Indicates whether the account is blocked for Instant ACH by Alpaca. Defaults to false when the partner creates the account. If the partner has set allow_instant_ach to true but instant_ach_blocked is true, then the account is blocked for Instant ACH irrespective of the fact that the partner has it enabled.

last_equitystring decimal required

EOD equity calculation (cash + long market value + short market value)

primary_account_holder_idstring uuid nullable

UUID that identifies the primary account holder (party) for accounts opened under the Multi-Live Accounts (MLA) flow. Only populated when the account was created by referencing an existing account holder via primary_account_holder_id on POST /v1/accounts. Otherwise null. Currently only supported for account_type of trading and ira.

status'INACTIVE' | 'ONBOARDING' | 'SUBMITTED' | 'SUBMISSION_FAILED' | 'ACTION_REQUIRED' | 'ACCOUNT_UPDATED' | 'APPROVAL_PENDING' | 'APPROVED' | 'REJECTED' | 'ACTIVE' | 'ACCOUNT_CLOSED' required

Designates the current status of this account

Possible Values:

  • INACTIVE Account not set to trade given asset.
  • ONBOARDING An application is expected for this user, but has not been submitted yet.
  • SUBMITTED The application has been submitted and is being processed.
  • SUBMISSION_FAILED Used to display if failure on submission
  • ACTION_REQUIRED The application requires manual action.
  • ACCOUNT_UPDATED Used to display when Account has been modified by user
  • APPROVAL_PENDING Initial value. The application approval process is in progress.
  • APPROVED The account application has been approved, and waiting to be ACTIVE
  • REJECTED The account application is rejected for some reason
  • ACTIVE The account is fully active. Trading and funding are processed under this status.
  • ACCOUNT_CLOSED The account is closed.

Example response

{
  "account_type": "trading",
  "agreements": [
    {
      "agreement": "customer_agreement",
      "ip_address": "185.13.21.99",
      "signed_at": "2019-09-11T18:09:33Z"
    }
  ],
  "cash_interest": {
    "USD": {
      "apr_tier_name": "gold",
      "status": "ACTIVE"
    }
  },
  "contact": {
    "city": "San Mateo",
    "country": "USA",
    "email_address": "john.doe@example.com",
    "phone_number": "+15556667788",
    "postal_code": "94401",
    "state": "CA",
    "street_address": [
      "20 N San Mateo Dr"
    ]
  },
  "crypto_status": "ACTIVE",
  "disclosures": {
    "immediate_family_exposed": false,
    "is_affiliated_exchange_or_finra": false,
    "is_control_person": false,
    "is_politically_exposed": false
  },
  "documents": [
    {
      "created_at": "2019-09-30T23:55:31.185998Z",
      "document_sub_type": "passport",
      "document_type": "identity_verification",
      "id": "0d18ae51-3c94-4511-b209-101e1666416b",
      "mime_type": "image/jpeg"
    }
  ],
  "fpsl": {
    "US": {
      "status": "ACTIVE",
      "tier_id": "61e69015-8549-4bfd-b9c3-01e75843f47d"
    }
  },
  "identity": {
    "country_of_birth": "AUS",
    "country_of_citizenship": "AUS",
    "country_of_tax_residence": "USA",
    "date_of_birth": "1990-01-01",
    "family_name": "Doe",
    "funding_source": [
      "employment_income"
    ],
    "given_name": "John",
    "tax_id": "666-55-4321",
    "tax_id_type": "USA_SSN"
  },
  "status": "ACTIVE",
  "trusted_contact": {
    "email_address": "jane.doe@example.com",
    "family_name": "Doe",
    "given_name": "Jane"
  }
}