Create an Account

post

https://broker-api.giftcity.sandbox.in.alpaca.markets/v1/accounts

Create an account for a new or existing account holder. Required fields, eligibility, and initial status depend on the account type, enabled assets, and your correspondent configuration. Account status changes are available through the Account Status Events stream.

To create an account for an existing holder, provide primary_account_holder_id instead of inline holder information. Among the documented account types, existing holders are supported for trading and IRA accounts. Donor-advised accounts instead reference an existing legal entity with entity_id.

Body Params

Fields accepted when creating an account. Requirements vary by account type, enabled assets, existing holder agreements, and correspondent configuration. The server enforces conditional requirements that are not represented statically in this schema.

Account-specific requirements:

Trading accounts require inline identity plus contact, or an existing holder through primary_account_holder_id. Individual US equity accounts created with inline identity also require disclosures.
Custodial accounts require identity and minor_identity. US equity accounts also require disclosures.
IRA accounts require account_sub_type, US equity, and either inline identity or an existing holder through primary_account_holder_id; they do not support crypto. IRA accounts created with inline identity also require disclosures.
Donor-advised accounts require entity_id.

account_sub_type

string

enum

The account subtype. Required for IRA accounts.

Allowed:

account_type

string

enum

Defaults to trading

The account type. Defaults to trading when omitted.

Allowed:

agreements

array of objects

Agreements submitted for the account or holder. Required agreement types depend on account type, enabled assets, existing holder agreements, and correspondent configuration. The server validates required coverage.

agreements

allow_instant_ach

boolean

Defaults to false

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

beneficiaries

array of objects

IRA Account only. A user can submit max 6 beneficiaries.

beneficiaries

cash_interest

object

The configuration of the account's USD cash interest program when creating an account.
If cash_interest is not provided and there is a default APR tier defined, that tier will be used.
To enroll the account in a non-default APR tier, provide the cash_interest object with the desired apr_tier_name. The status should not be specified on enrollment.
The response will contain a status of PENDING_CHANGE. An event showing the status change to ACTIVE will be generated when the enrollment is complete.

contact

object

Contact is the model for the account owner contact information.

disclosures

object

Disclosures fields denote if the account owner falls under
each category defined by FINRA rule. The client has to ask
questions for the end user and the values should reflect
their answers.
If one of the answers is true (yes), the account goes into
ACTION_REQUIRED status.

documents

array of objects

documents

enabled_assets

array of objects

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

enabled_assets

Allowed:

entity_id

uuid

UUID of an existing legal entity used as the holder of a donor-advised account. Required for donor-advised accounts.

fpsl

object

The account's Fully Paid Securities Lending (FPSL) configuration.
To enroll the account for a market, specify the tier_id. The status should not be specified on enrollment.
Currently only the US market is supported.

identity

object

Identity is the model to provide account owner's identity information.

investment_objective

string

enum

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

Allowed:

investment_time_horizon

string

enum

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.

Allowed:

liquidity_needs

string

enum

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.

Allowed:

minor_identity

object

Identity information for the minor. Required for custodial accounts.

primary_account_holder_id

uuid

UUID of an existing party to use as the primary account holder. Among the documented account types, existing holders are supported for trading and IRA accounts.

When provided, omit inline holder fields such as contact, identity, disclosures, and minor_identity. The server validates the referenced party, account-type compatibility, eligibility, and required agreements.

risk_tolerance

string

enum

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

Allowed:

trading_configurations

object

Represents additional configuration settings for an account

trusted_contact

object

This model input is optional. However, the client should make a reasonable effort to obtain the trusted contact information. See FINRA Notice 17-11 for more details.

At least one of the following is required:

email_address
phone_number
street_address

Responses

409

There is already an existing account registered with the same email address.

Language

Credentials

Basic

base64

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200OK

400The request body is malformed or cannot be decoded.

422The request is well-formed but fails account-creation validation. This can include conflicting inline and referenced holder data, an unsupported account-type and holder combination, or an ineligible referenced party.