Accounts #

The Accounts API allows you to create and manage the accounts under your brokerage and crypto account.

This content is provided as a guide, and will be different per broker, per region. More information can be found through the Broker Dashboard. Click here to login or sign up.

Allowed Setups #

Fully-Disclosed: Brokers with an FD setup can access the Accounts API

Omnibus: Brokers with an Omnibus setup cannot access the Accounts API

The Account Model #

Sample Account Object #

{
    "id": "7ccfd029-9b91-40d0-9b4c-f928385af666",
    "account_number": "808971365",
    "status": "SUBMITTED",
    "crypto_status": "SUBMITTED",
    "currency": "USD",
    "last_equity": "0",
    "created_at": "2022-08-16T20:19:20.547306Z",
    "contact": {
        "email_address": "[email protected]",
        "phone_number": "555-666-7788",
        "street_address": [
            "20 N San Mateo Dr"
        ],
        "city": "San Mateo",
        "state": "CA",
        "postal_code": "94401"
    },
    "identity": {
        "given_name": "John",
        "family_name": "Doe",
        "date_of_birth": "1990-01-01",
        "tax_id_type": "USA_SSN",
        "country_of_citizenship": "USA",
        "country_of_birth": "USA",
        "country_of_tax_residence": "USA",
        "funding_source": [
            "employment_income"
        ],
        "visa_type": null,
        "visa_expiration_date": null,
        "date_of_departure_from_usa": null,
        "permanent_resident": null
    },
    "disclosures": {
        "is_control_person": false,
        "is_affiliated_exchange_or_finra": false,
        "is_politically_exposed": false,
        "immediate_family_exposed": false,
        "is_discretionary": false
    },
    "agreements": [
        {
            "agreement": "customer_agreement",
            "signed_at": "2020-09-11T18:13:44Z",
            "ip_address": "185.13.21.99",
            "revision": "19.2022.02"
        },
        {
            "agreement": "crypto_agreement",
            "signed_at": "2020-09-11T18:13:44Z",
            "ip_address": "185.13.21.99",
            "revision": "04.2021.10"
        }
    ],
    "documents": [
        {
            "document_type": "identity_verification",
            "document_sub_type": "passport",
            "id": "91098d44-c384-4388-a410-24616ce1c6e4",
            "content": "https://s3.amazonaws.com/stg.alpaca.markets/documents/accounts/7ccfd029-9b91-40d0-9b4c-f928385af666/af49b170-a4ba-4592-8036-db43964756c0.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJLDF4SCWSL6HUQKA%2F20220816%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220816T202138Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=a22b2eb92e373fd4146d10a4707765d35042f3cbd7c319341a718d9d823f5350",
            "created_at": "2022-08-16T20:19:21.333788Z"
        }
    ],
    "trusted_contact": {
        "given_name": "Jane",
        "family_name": "Doe",
        "email_address": "[email protected]"
    },
    "account_type": "trading",
    "trading_configurations": null,
    "enabled_assets": [
        "us_equity",
        "crypto"
    ]
}

Attributes #

Helpful Hint

Here we outline a comprehensive overview of a full Account model attributes. To receive such an extended object of an account use Retrieve An Account (By ID), other Account APIs might return a more simplified version of the Account model.

Enabled Assets #

Contact #

Identity #

Disclosures #

It is your responsibility as the service provider to denote if the account owner falls under each category defined by FINRA rules. We recommend asking these questions at any point of the onboarding process of each account owner in the form of Y/N and Radio Buttons.

Agreements

In order to comply with Alpaca’s terms of service, each account owner must be presented the following agreements.

Documents #

1. ​DocumentUpload

   This model consists of a series of documents based on the KYC and international taxation requirements. Documents are binary objects whose contents are encoded in base64. Each encoded content size is limited to 10MB if you use Alpaca for KYCaaS. If you perform your own KYC there are no document size limitations. The only exception is the W-8BEN form which we accept in multiple formats.

   Attribute	Type
   document_type	ENUM.DocumentType
   document_sub_type	string
   content	base64 string
   mime_type	string

2. Document

   To add an additional document after submission, please use the Document model below to replace any DocumentUpload

   Attribute	Type
   document_type	ENUM.DocumentType
   document_sub_type	string
   id	UUID
   mime_type	string
   created_at	timestamp string

Trusted Contact #

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

In addition, only one of the following is required,

Enums #

Asset Class #

Account Type #

Tax ID Type #

• Please feel free to reach out to Alpaca if you need other tax ID types.

Funding Source #

Visa Type #

In addition to the following USA visa categories, we accept any sub visas of the list below. Sub visas must be passed in according to their parent category. Note that United States green card holders are considered permanent residents and should not pass in a visa type.

Employment Status #

Context Type #

Agreements #

Document Type #

Account Status #

Crypto Status #

Fixtures #

Accounts API supports fixtures in Sandbox Environment. You can pass the desired account status in the optional parameter additional_information when creating an account. Note that this parameter is not listed above in the account model as it is only to be used in the Sandbox Environment for testing purposes.

Sample Fixture #

Simulating a rejected account.

{
  "additional_information": "/fixtures/status=REJECTED/fixtures/"
}

Creating an Account #

POST /v1/accounts

Submit an account application with KYC information. This will create a trading account for the end user. The account status may or may not be ACTIVE immediately and you will receive account status updates on the event API.

Request #

Sample Request Model #

{
  "enabled_assets": ["us_equity", "crypto"],
  "contact": {
    "email_address": "[email protected]",
    "phone_number": "555-666-7788",
    "street_address": ["20 N San Mateo Dr"],
    "unit": "Apt 1A",
    "city": "San Mateo",
    "state": "CA",
    "postal_code": "94401",
    "country": "USA"
  },
  "identity": {
    "given_name": "John",
    "middle_name": "Smith",
    "family_name": "Doe",
    "date_of_birth": "1990-01-01",
    "tax_id": "666-55-4321",
    "tax_id_type": "USA_SSN",
    "country_of_citizenship": "USA",
    "country_of_birth": "USA",
    "country_of_tax_residence": "USA",
    "funding_source": ["employment_income"]
  },
  "disclosures": {
    "is_control_person": false,
    "is_affiliated_exchange_or_finra": true,
    "is_politically_exposed": false,
    "immediate_family_exposed": false,
    "context": [
      {
        "context_type": "AFFILIATE_FIRM",
        "company_name": "Finra",
        "company_street_address": ["1735 K Street, NW"],
        "company_city": "Washington",
        "company_state": "DC",
        "company_country": "USA",
        "company_compliance_email": "[email protected]"
      }
    ]
  },
  "agreements": [
    {
      "agreement": "customer_agreement",
      "signed_at": "2020-09-11T18:13:44Z",
      "ip_address": "185.13.21.99",
      "revision": "19.2022.02"
    },
    {
      "agreement": "crypto_agreement",
      "signed_at": "2020-09-11T18:13:44Z",
      "ip_address": "185.13.21.99",
      "revision": "04.2021.10"
    }
  ],
  "documents": [
    {
      "document_type": "identity_verification",
      "document_sub_type": "passport",
      "content": "/9j/Cg==",
      "mime_type": "image/jpeg"
    }
  ],
  "trusted_contact": {
    "given_name": "Jane",
    "family_name": "Doe",
    "email_address": "[email protected]"
  }
}

Please note that the API level requirements may not be aligned with the regulatory requirements of what you are required to collect from your users to create an account. You should always refer to the onboarding requirements document that Alpaca shares with you to determine what fields you are required to collect.

Parameters #

Enabled Assets

Contact

Identity

Disclosures

It is your responsibility as the service provider to denote if the account owner falls under each category defined by FINRA rules. We recommend asking these questions at any point of the onboarding process of each account owner in the form of Y/N and Radio Buttons.

DisclosureContext

If you utilize Alpaca for KYCaaS, additional information will need to be submitted if the user identifies with any of the disclosures before the account can be approved. This information can be sent through the context object to speed up the time to approve their account.

Agreements

In order to comply with Alpaca’s terms of service, each account owner must be presented the following agreements.

Documents

1. ​DocumentUpload

   This model consists of a series of documents based on the KYC requirements. Documents are binary objects whose contents are encoded in base64. Each encoded content size is limited to 10MB if you use Alpaca for KYCaaS. If you perform your own KYC there are no document size limitations.

   Attribute	Type	Required
   document_type	ENUM.DocumentType	Required
   document_sub_type	string	Optional
   content	base64 string	Required
   mime_type	string	Required

2. Document

   To add an additional document after submission, please use the Document model below to replace any DocumentUpload

   Attribute	Type	Required
   document_type	ENUM.DocumentType	Required
   document_sub_type	string	Optional
   id	UUID	Required
   mime_type	string	Required
   created_at	timestamp string	Required

Trusted Contact

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

In addition, only one of the following is required,

Response #

Parameters #

If all parameters are valid and the application is accepted, you should receive a status code 200 with the following response model.

Sample Response Body #

{
    "id": "de9d0029-e0a0-4a2f-b630-265a32dd00c4",
    "account_number": "808333970",
    "status": "SUBMITTED",
    "crypto_status": "SUBMITTED",
    "currency": "USD",
    "last_equity": "0",
    "created_at": "2022-08-16T20:36:07.514367Z",
    "contact": {
        "email_address": "[email protected]",
        "phone_number": "555-666-7788",
        "street_address": [
            "20 N San Mateo Dr"
        ],
        "unit": "Apt 1A",
        "city": "San Mateo",
        "state": "CA",
        "postal_code": "94401"
    },
    "identity": {
        "given_name": "John",
        "family_name": "Doe",
        "middle_name": "Smith",
        "date_of_birth": "1990-01-01",
        "tax_id_type": "USA_SSN",
        "country_of_citizenship": "USA",
        "country_of_birth": "USA",
        "country_of_tax_residence": "USA",
        "funding_source": [
            "employment_income"
        ],
        "visa_type": null,
        "visa_expiration_date": null,
        "date_of_departure_from_usa": null,
        "permanent_resident": null
    },
    "disclosures": {
        "is_control_person": false,
        "is_affiliated_exchange_or_finra": true,
        "is_politically_exposed": false,
        "immediate_family_exposed": false,
        "is_discretionary": false
    },
    "agreements": [
      {
        "agreement": "customer_agreement",
        "signed_at": "2020-09-11T18:13:44Z",
        "ip_address": "185.13.21.99",
        "revision": "19.2022.02"
      },
      {
        "agreement": "crypto_agreement",
        "signed_at": "2020-09-11T18:13:44Z",
        "ip_address": "185.13.21.99",
        "revision": "04.2021.10"
      }
    ],
    "trusted_contact": {
        "given_name": "Jane",
        "family_name": "Doe",
        "email_address": "[email protected]"
    },
    "account_type": "trading",
    "trading_configurations": null,
    "enabled_assets": [
        "us_equity",
        "crypto"
    ]
}

Error Codes #

400 - Bad Request

​ The body in the request is not valid

409 - Conflict

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

422 - Unprocessable Entity

​ Invalid input value.

500 - Internal Server Error​

Some server error occurred. Please contact Alpaca.

Retrieving an Onfido SDK Token #

GET /v1/accounts/{account_id}/onfido/sdk/tokens/

Get an SDK token to activate the Onfido SDK flow within your app. You will have to keep track of the SDK token so you can pass it back when you upload the SDK outcome. We recommend storing the token in memory rather than persistent storage to reduce any unnecessary overhead in your app.

Request #

Parameters #

Response #

{
  "token": "header.payload.signature"
}

Error Codes #

422 - Unprocessable Entity

​ Onfido applicant not yet created for account. If you haven’t already contacted Alapca to enable Onfido, please do so.

500 - Internal Server Error​

Some server error occurred. Please contact Alpaca.

Updating the Onfido SDK Outcome #

PATCH /v1/accounts/{account_id}/onfido/sdk/

This request allows you to send Alpaca the result of the Onfido SDK flow in your app. A notification of a successful outcome is required for Alpaca to continue the KYC process.

Request #

Sample Request Body #

{
  "outcome": "USER_EXITED",
  "reason": "User denied consent",
  "token": "header.payload.signature"
}

Parameters #

Enums #

Outcome #

Response #

If all parameters are valid and updates have been made, it returns with status code 200.

Error Codes #

404 - Account Not Found​

422 - Unprocessable Entity

​ Invalid input value for outcome.

500 - Internal Server Error​

Some server error occurred. Please contact Alpaca.

Uploading CIP information #

POST /v1/accounts/{account_id}/cip

The customer identification program (CIP) API allows you to submit the CIP results received from your KYC provider.

Financial institutions and other obliged entities must have reasonable procedures to gather and maintain information on customers’ identities, along with running watchlist checks on them.

The minimum requirements to open an individual financial account are delimited and you must verify the true identity of the account holder at account opening:

• Name
• Date of birth
• Address
• Identification number (for a U.S. citizen, a taxpayer identification number)

Procedures for identity verification include documents (for example, driver’s licenses and passports), non-documentary methods (for example, data sources like credit bureaus and government databases), or a combination of both.

Request #

Sample Request Body #

{
  "provider_name": ["onfido"],
  "kyc": {
    "id": "CBDAD1C4-1047-450E-BAE5-B6C406F509B4",
    "risk_level": "LOW",
    "applicant_name": "John Doe",
    "email_address": "[email protected]",
    "nationality": "American",
    "id_number": "jd0000123456789",
    "date_of_birth": "1970-12-01",
    "address": "42 Faux St",
    "postal_code": "94401",
    "country_of_residency": "USA",
    "kyc_completed_at": "2021-06-10T15:37:03Z",
    "ip_address": "127.0.0.1",
    "check_initiated_at": "2021-06-10T15:37:03Z",
    "check_completed_at": "2021-06-10T15:37:03Z",
    "approval_status": "approved",
    "approved_by": "Jane Doe",
    "approved_at": "2021-06-10T15:38:03Z"
  },
  "document": {
    "id": "55B9931A-3BE6-4BC0-9BDD-0B954E4A4632",
    "result": "clear",
    "status": "complete",
    "created_at": "2021-06-10T15:37:03Z",
    "image_integrity": "clear"
  },
  "photo": {
    "id": "0DD13020-F0FD-4B5A-B58F-BC1885E90A6D",
    "result": "clear",
    "status": "complete",
    "created_at": "2021-06-10T15:37:03Z",
    "face_comparison": "clear"
  },
  "identity": {
    "id": "28E1CCE8-1B1A-4472-9AD4-C6C5B7C3A6AF",
    "result": "clear",
    "status": "complete",
    "created_at": "2021-06-10T15:37:03Z",
    "sources": "clear",
    "address": "clear",
    "date_of_birth": "clear"
  },
  "watchlist": {
    "id": "7572B870-EB4C-46A2-8B88-509194CCEE7E",
    "result": "clear",
    "status": "complete",
    "created_at": "2021-06-10T15:37:03Z",
    "politically_exposed_person": "clear",
    "sanction": "clear",
    "adverse_media": "clear",
    "monitored_lists": "clear"
  }
}

Parameters #

KYC

Document

Photo

Identity

Watchlist

Enums #

CIP Result #

CIP Status #

CIP Provider #

This list contains the KYC providers that have been whitelisted by Alpaca. In case you

Retrieving CIP information #

GET /v1/accounts/{account_id}/cip

You can retrieve the CIP information you’ve submitted for a given account.

Request #

N/A

Response #

It will return the CIP ID generated on submission, account_id, and CIP data if it exists otherwise will throw an error.

International Accounts #

W-8 BEN #

For certain individuals, a W-8 BEN form should be submitted at onboarding. If the individual is not a registered U.S. taxpayer (not subject to a W-9), the W-8 BEN form may need to be submitted. The IRS explains here which individuals this applies to and provides instructions on completing the form. Every three years, in addition to the calendar year it was signed, a new W-8 BEN form must be submitted.

The form can be submitted in JSON, JSONC, PNG, JPEG or PDF. If submitting it in JSON, please see the W-8 BEN completed with the corresponding field names for the API here.

Note: The dates collected on the form are in a slightly different format than how they need to be submitted via Accounts API. It is requested by the user on the form in MM-DD-YYYY, but should be submitted as YYYY-MM-DD.

Sample Request Body #

Note: This W-8 BEN sample is document object that will be included in the documents parameter of the account object.

{
  "document_type": "w8ben",
  "content_data": {
    "additional_conditions": "None",
    "country_citizen": "Australia",
    "date": "2021-06-14",
    "date_of_birth": "1970-01-01",
    "foreign_tax_id": "123 456 789",
    "ftin_not_required": false,
    "full_name": "John Doe",
    "ip_address": "127.0.0.1",
    "mailing_address_city_state": "Adelaide, South Australia",
    "mailing_address_country": "Australia",
    "mailing_address_street": "51 Main St",
    "paragraph_number": "15",
    "percent_rate_withholding": 5.0,
    "permanent_address_city_state": "Adelaide, South Australia",
    "permanent_address_country": "Australia",
    "permanent_address_street": "20 Main St",
    "reference_number": "abc123",
    "residency": "Australia",
    "revision": "10-2021",
    "tax_id_ssn": "123-00-456",
    "timestamp": "2021-06-14T09:31:05Z",
    "income_type": "interest",
    "signer_full_name": "Mr. Signing User"
  }
}

Parameters #

Listing All Accounts #

GET /v1/accounts

You can query a list of all the accounts that you submitted to Alpaca. You can tweak the query to return a list of accounts that fulfill certain conditions passed.

Request #

Parameters #

Response #

Up to 1,000 items per query, ordered by created_at.

Retrieving an Account (Brokerage) #

GET /v1/accounts/{account_id}

You can query a specific account that you submitted to Alpaca by passing into the query the account_id associated with the account you’re retrieving.

Request #

N/A

Response #

Will return an account if account with account_id exists, otherwise will throw an error.

422 - Unprocessable Entity

account_id is missing.

Retrieving an Account (Trading) #

GET /v1/trading/accounts/{account_id}/account

As a broker you can view more trading details about your users.

Request #

N/A

Response #

Sample Response #

The response is a much more expanded account object found here in Trading API

{
  "id": "c8f1ef5d-edc0-4f23-9ee4-378f19cb92a4",
  "account_number": "927584925",
  "status": "ACTIVE",
  "crypto_status": "ACTIVE",
  "currency": "USD",
  "buying_power": "103556.8572572922",
  "regt_buying_power": "52921.2982330664",
  "daytrading_buying_power": "103556.8572572922",
  "cash": "24861.91",
  "cash_withdrawable": "17861.91",
  "cash_transferable": "24861.91",
  "accrued_fees": "0",
  "pending_transfer_out": "0",
  "portfolio_value": "28059.3882330664",
  "pattern_day_trader": true,
  "trading_blocked": false,
  "transfers_blocked": false,
  "account_blocked": false,
  "created_at": "2021-03-01T13:28:49.270232Z",
  "trade_suspended_by_user": false,
  "multiplier": "4",
  "shorting_enabled": true,
  "equity": "28059.3882330664",
  "last_equity": "26977.323677655",
  "long_market_value": "3197.4782330664",
  "short_market_value": "0",
  "initial_margin": "1598.7391165332",
  "maintenance_margin": "959.24346991992",
  "last_maintenance_margin": "934.6241032965",
  "sma": "26758.0590204615",
  "daytrade_count": 0,
  "previous_close": "2021-04-01T19:00:00-04:00",
  "last_long_market_value": "3115.413677655",
  "last_short_market_value": "0",
  "last_cash": "23861.91",
  "last_initial_margin": "1557.7068388275",
  "last_regt_buying_power": "50839.233677655",
  "last_daytrading_buying_power": "104433.9158860662",
  "last_buying_power": "104433.9158860662",
  "last_daytrade_count": 0,
  "clearing_broker": "VELOX"
}

Attributes #

AdminConfigurations #

These configurations show account properties that are overriden either by Alpaca Broker Operations or an automated process.

These values cannot be modified by the Broker Partners.

RestrictToLiquidationReasons #

Updating an Account #

PATCH /v1/accounts/{account_id}

This operation updates account information. The following attribute are modifiable.

Request #

Parameters #

Enabled Assets

Contact

• Partners are responsible for submitting updated documents as required by the updates being made
• Guidance for Form W-8 BEN on changes in circumstance can be found here
• Letters sent to customers on address changes should blind carbon copy (bcc) [email protected]

Identity

Disclosures

Trusted Contact

You can change the name of the trusted contact if you want.

In addition, you can also change the way to reach the trusted contact by updating the following. Only one of email_address, phone_number or streets_address (with the other parameters) is required

Response #

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

Error Codes #

400 - Bad Request

​ The body in the request is not valid

422 - Unprocessable Entity

​ The request body contains an attribute that is not permitted to be updated.

500 - Internal Server Error​

Some server error occurred. Please contact Alpaca.

Close an Account #

POST /v1/accounts/{account_id}/actions/close

This operation closes an active account. The underlying records and information of the account are not deleted by this operation.

Before closing an account, you are responsible for closing all the positions and withdrawing all the money associated with that account. Learn more in the Positions Documentation.

Request #

In the account_id path parameter, provide the id of the account to be closed.

Response #

204 - No Content

403 - Forbidden

404 - Account Not Found​

422 - Unprocessable Entity

Reopen a Closed Account #

POST /v1/accounts/{account_id}/actions/reopen

This operation re-activates an account that is in the ACCOUNT_CLOSED status. Currently, this is only available if you are working with the CIP API setup and it requires a CIP document to be uploaded to the account within at least 30 days of the attempt to reopen the account.

Request #

In the account_id path parameter, provide the id of the account to be reopened.

Response #

If the request is succesfully processed it returns with status code 200. The response is the account model.

Error Codes #

401 - Unauthorized

404 - Account Not Found​

422 - Unprocessable Entity

500 - Internal Server Error