Sign in

v1

latestOpenAPI 3.0.02026-07-26166415635.8 KB
Accounts

Get All Accounts

Retrieves the first 1000 accounts that match the query parameters. Sorting is based on creation time. The created_after/created_before query parameters can be used to paginate the results. To further limit the size of the response, the entities query parameter can be used to specify which properties are included in the response.

get/v1/accounts

Query parameters

querystring

A space-delimited list of tokens. The response will contain accounts that match with all of the tokens (i.e. a logical AND). A match means the token is present in either the account's associated account number, phone number, name, or e-mail address (logical OR).

created_afterstring date-time

Inclusive of timestamp. Example: 2019-10-12T07:20:50.52Z

created_beforestring date-time

Inclusive of timestamp. Example: 2019-10-12T07:20:50.52Z

statusstring

See the AccountStatus model for values

sort'asc' | 'desc'
Example:desc

The chronological order of response based on the submission time. asc or desc. Defaults to desc.

entities'agreements' | 'contact' | 'disclosures' | 'documents' | 'identity' | 'trading_configurations' | 'trusted_contact'

Comma-delimited entity names to include in the response. If not specified, all entities are included.

Response

A list of accounts that match the query parameters.

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"
    }
  }
]