Sign in

v1

latestOpenAPI 3.0.02026-07-26166415635.8 KB
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.

Multi-Live Accounts (MLA): The primary_account_holder_id field is read-only after the account is created. Omitting it or supplying the value already associated with the account is a no-op; supplying a different value returns HTTP 400.

patch/v1/accounts/{account_id}

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.

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

Example request

{
  "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
  },
  "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"
  },
  "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' required

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

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_assetsAssetClass[]
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 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.

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' | '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_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"
    ]
  },
  "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"
  },
  "minor_identity": {
    "tax_id_type": "USA_SSN"
  },
  "status": "ACTIVE",
  "trusted_contact": {
    "email_address": "jane.doe@example.com",
    "family_name": "Doe",
    "given_name": "Jane"
  },
  "usd": {
    "last_equity": "123.45"
  }
}