ALalpacahq
Accounts

Update an Account

This operation updates account information.

If all parameters are valid and updates have been made, it returns with status code 200. The response is the account model.

patch/v1/accounts/{account_id}

Request

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

Request body

allow_instant_achboolean

If provided, updates whether the account is enabled for Instant ACH by the partner. Omitting the field leaves the current setting unchanged.

enabled_assetsEnabledAssetClass[]

The asset classes enabled on the account. Omit this field to leave the account's enabled assets unchanged. Updates are additive only: the submitted list must contain every asset class already enabled on the account, because asset removal is not supported. For example, to enable crypto for an account that currently trades only equities, submit ["us_equity", "crypto"] together with the signed crypto agreement. us_option may appear in this list for options-enabled accounts and must be re-listed on additive updates, but options cannot be enabled through this endpoint.

primary_account_holder_idstring uuid

The UUID of the primary account holder. This field is immutable after the account is created.

  • Omitting the field, or supplying the value already associated with the account, is a no-op.
  • Supplying a value different from the current primary account holder returns HTTP 403.

Example request

{
  "beneficiaries": [
    {
      "date_of_birth": "1970-01-01",
      "family_name": "Smith",
      "given_name": "John",
      "middle_name": "P",
      "relationship": "spouse",
      "share_pct": "100",
      "tax_id": "666-55-1234",
      "tax_id_type": "USA_SSN",
      "type": "primary"
    }
  ],
  "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
  },
  "enabled_assets": [
    "us_equity",
    "crypto"
  ],
  "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

If all parameters are valid and updates have been made, it returns with status code 200. The response is the account model.

account_namestring
account_numberstring nullable required
account_sub_type'traditional' | 'roth'

IRA Account only

Possible values are:

  • traditional
  • roth
account_type'trading' | 'custodial' | 'donor_advised' | 'ira' | 'trust' | 'omnibus_non_disclosed' | 'omnibus_sub' | 'hsa' | 'joint' required

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
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

custodial_account_typestring

Represents the type of custodial account based on the state where the beneficiary resides. This value is returned only when the country_of_tax_residence is USA. For other countries, this property is not included in the response.

Possible Return Values

CustodianTypeUTMA - Indicates that the custodial account is governed by the Uniform Transfers to Minors Act. CustodianTypeUGMA - Indicates that the custodial account is governed by the Uniform Gifts to Minors Act.

enabled_assetsEnabledAssetClass[]
idstring uuid required
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.

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.

last_equitystring decimal required
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 nullable

UUID of the account's primary holder when available; otherwise null.

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.

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": "601842165",
  "account_type": "trading",
  "agreements": [
    {
      "agreement": "margin_agreement",
      "ip_address": "127.0.0.1",
      "revision": "16.2021.05",
      "signed_at": "2022-01-21T21:25:26.579487214Z"
    },
    {
      "agreement": "customer_agreement",
      "ip_address": "127.0.0.1",
      "revision": "22.2024.08",
      "signed_at": "2022-01-21T21:25:26.579487214Z"
    }
  ],
  "beneficiaries": [
    {
      "date_of_birth": "1970-01-01",
      "family_name": "Smith",
      "given_name": "John",
      "middle_name": "P",
      "relationship": "spouse",
      "share_pct": "100",
      "tax_id": "xxx-xx-xxxx",
      "tax_id_type": "USA_SSN",
      "type": "primary"
    }
  ],
  "contact": {
    "city": "San Mateo",
    "country": "USA",
    "email_address": "strange_elbakyan_97324509@example.com",
    "phone_number": "614-555-0697",
    "postal_code": "94401",
    "state": "CA",
    "street_address": [
      "20 N San Mateo Dr"
    ]
  },
  "created_at": "2022-01-21T21:25:26.583576Z",
  "crypto_status": "INACTIVE",
  "currency": "USD",
  "disclosures": {
    "immediate_family_exposed": false,
    "is_affiliated_exchange_or_finra": false,
    "is_control_person": false,
    "is_discretionary": false,
    "is_politically_exposed": false
  },
  "documents": [
    {
      "content": "https://example.com/documents/identity-verification.jpg",
      "created_at": "2022-01-21T21:25:28.184231Z",
      "document_sub_type": "passport",
      "document_type": "identity_verification",
      "id": "d5af1585-6c60-494d-9ea5-c5df62704229"
    }
  ],
  "id": "3dcb795c-3ccc-402a-abb9-07e26a1b1326",
  "identity": {
    "country_of_birth": "USA",
    "country_of_citizenship": "USA",
    "country_of_tax_residence": "USA",
    "date_of_birth": "1970-01-01",
    "family_name": "Elbakyan",
    "funding_source": [
      "employment_income"
    ],
    "given_name": "Strange",
    "tax_id_type": "USA_SSN"
  },
  "last_equity": "40645.13",
  "primary_account_holder_id": null,
  "status": "ACTIVE",
  "trusted_contact": {
    "email_address": "strange_elbakyan_97324509@example.com",
    "family_name": "Doe",
    "given_name": "Jane"
  }
}

Changes

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