ALalpacahq
Accounts

Create an Account

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.

post/v1/accounts

Request

  • Base URL
    https://broker-api.giftcity.sandbox.in.alpaca.markets
  • URL
    https://broker-api.giftcity.sandbox.in.alpaca.markets/v1/accounts
  • Auth
    HTTP basic

Request body

account_sub_type'traditional' | 'roth'

IRA Account only

Possible values are:

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

The account type to create.

allow_instant_achboolean

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

enabled_assetsEnabledAssetClass[]

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

entity_idstring uuid

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

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 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'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": null,
      "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"
  },
  "minor_identity": {
    "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' | 'trust' | 'omnibus_non_disclosed' | 'omnibus_sub' | 'hsa' | 'joint'

The account type returned for the account.

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' | 'PAPER_ONLY' | '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.
  • PAPER_ONLY The account is limited to paper trading.
  • 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_assetsEnabledAssetClass[]

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 of the account's primary holder when available; otherwise null.

status'INACTIVE' | 'PAPER_ONLY' | '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.
  • PAPER_ONLY The account is limited to paper trading.
  • 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_number": "9034005019",
  "created_at": "2019-09-30T23:55:31.185998Z",
  "currency": "USD",
  "id": "0d18ae51-3c94-4511-b209-101e1666416b",
  "last_equity": "1500.65",
  "primary_account_holder_id": null,
  "status": "APPROVED"
}

Changes

No recorded changes to this operation across all 1 revision of this API.