Account

Accounts #

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

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 #

{
  "contact": {
    "email_address": "cool_alpaca@example.com",
    "phone_number": "555-666-7788",
    "street_address": ["20 N San Mateo Dr"],
    "city": "San Mateo",
    "state": "CA",
    "postal_code": "94401",
    "country": "USA"
  },
  "identity": {
    "given_name": "John",
    "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": false,
    "is_politically_exposed": false,
    "immediate_family_exposed": false
  },
  "agreements": [
    {
      "agreement": "margin_agreement",
      "signed_at": "2020-09-11T18:09:33Z",
      "ip_address": "185.13.21.99"
    },
    {
      "agreement": "account_agreement",
      "signed_at": "2020-09-11T18:13:44Z",
      "ip_address": "185.13.21.99"
    },
    {
      "agreement": "customer_agreement",
      "signed_at": "2020-09-11T18:13:44Z",
      "ip_address": "185.13.21.99"
    }
  ],
  "documents": [
    {
      "document_type": "identity_verification",
      "document_sub_type": "passport",
      "content": "QWxwYWNhcyBjYW5ub3QgbGl2ZSBhbG9uZS4=",
      "mime_type": "image/jpeg"
    },
    {
      "document_type": "w8ben",
      "content": "RFerjiUxFUTXLQ7pMEckpWYjLPviLRZdrc4=",
      "mime_type": "application/pdf"
    }
  ],
  "trusted_contact": {
    "given_name": "Jane",
    "family_name": "Doe",
    "email_address": "jane.doe@example.com"
  }
}

Attributes #

Parameters #

Attribute Notes
contact Contact information about the user
identity KYC information about the user
disclosures Required disclosures about the user
documents Any documents that need to be uploaded (eg. passport, visa, …)
trusted_contact The contact information of a trusted contact to the user in case account recovery is needed.

Contact

Attribute Type
email_address string
phone_number string
street_address array
city string
state string
postal_code string

Identity

Attribute Type
given_name string
family_name string
date_of_birth date
tax_id string
tax_id_type ENUM.TaxIdType
country_of_citizenship string
country_of_birth string
country_of_tax_residence string
funding_source array of ENUM.FundingSource
annual_income_min string/number
annual_income_max string/number
liquid_net_worth_min string/number
liquid_net_worth_max string/number
total_net_worth_min string/number
total_net_worth_max string/number
extra object

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.

Attribute Type
is_control_person boolean
is_affiliated_exchange_or_finra boolean
is_politically_exposed boolean
immediate_family_exposed boolean
employment_status ENUM.EmploymentStatus
employer_name string
employer_address string
employment_position string

Agreements

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

Attribute Type
[].agreement ENUM.DocumentType
[].signed_at string (timestamp)
[].ip_address string

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

Attribute Type Notes
given_name string First name
family_name string Last name

In addition, only one of the following is required,

Attribute Type
email_address string
phone_number string
street_address string
city string
state string
postal_code string
country string

Enums #

Tax ID Type #

Attribute Description
USA_SSN USA Social Security Number
ARG_AR_CUIT Argentina CUIT
AUS_TFN Australian Tax File Number
AUS_ABN Australian Business Number
BOL_NIT Bolivia NIT
BRA_CPF Brazil CPF
CHL_RUT Chile RUT
COL_NIT Colombia NIT
CRI_NITE Costa Rica NITE
DEU_TAX_ID Germany Tax ID (Identifikationsnummer)
DOM_RNC Dominican Republic RNC
ECU_RUC Ecuador RUC
FRA_SPI France SPI (Reference Tax Number)
GBR_UTR UK UTR (Unique Taxpayer Reference)
GBR_NINO UK NINO (National Insurance Number)
GTM_NIT Guatemala NIT
HND_RTN Honduras RTN
HUN_TIN Hungary TIN Number
IND_PAN India PAN Number
ISR_TAX_ID Israel Tax ID (Teudat Zehut)
ITA_TAX_ID Italy Tax ID (Codice Fiscale)
JPN_TAX_ID Japan Tax ID (Koijin Bango)
MEX_RFC Mexico RFC
NIC_RUC Nicaragua RUC
NLD_TIN Netherlands TIN Number
PAN_RUC Panama RUC
PER_RUC Peru RUC
PRY_RUC Paraguay RUC
SGP_NRIC Singapore NRIC
SGP_FIN Singapore FIN
SGP_ASGD Singapore ASGD
SGP_ITR Singapore ITR
SLV_NIT El Salvador NIT
SWE_TAX_ID Sweden Tax ID (Personnummer)
URY_RUT Uruguay RUT
VEN_RIF Venezuela RIF
NOT_SPECIFIED Other Tax IDs
  • Please feel free to reach out to Alpaca if you need other tax ID types.

Funding Source #

Attribute Description
employment_income Employment income
investments Investments
inheritance Inheritance
business_income Business income
savings Savings
family Family

Employment Status #

Attribute Description
unemployed Unemployed
employed Employed
student Student
retired Retired

Agreements #

Attribute Description
margin_agreement Margin agreement
account_agreement Account agreement
customer_agreement Customer agreement

Document Type #

Attribute Description
identity_verification Identity verification
address_verification Address verification
date_of_birth_verification Date of birth verification
tax_id_verification Tax ID verification
account_approval_letter 407 approval letter
w8ben W-8 BEN tax form

Account Status #

Attribute Description
SUBMITTED Application has been submitted and in process of review
ACTION_REQUIRED Application requires manual action
APPROVAL_PENDING Initial value. Application approval process is in process
APPROVED Account application has been approved, waiting to be ACTIVE
REJECTED Account application is rejected
ACTIVE Account is fully active. Trading and funding can only be processed if an account is ACTIVE.
DISABLED Account is disabled, comes after ACTIVE
ACCOUNT_CLOSED Account is closed

Fixtures #

Accounts API supports fixtures in Sandbox Environment. You can pass the desired account status in the optional additional_information field when creating an account.

Attribute Description
SUBMITTED /fixtures/status=SUBMITTED/fixtures/
ACTION_REQUIRED /fixtures/status=ACTION_REQUIRED/fixtures/
APPROVAL_PENDING /fixtures/status=APPROVAL_PENDING/fixtures/
APPROVED /fixtures/status=APPROVED/fixtures/
REJECTED /fixtures/status=REJECTED/fixtures/
ACTIVE /fixtures/status=ACTIVE/fixtures/
DISABLED /fixtures/status=DISABLED/fixtures/
ACCOUNT_CLOSED /fixtures/status=ACCOUNT_CLOSED/fixtures/

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 #
{
  "contact": {
    "email_address": "cool_alpaca@example.com",
    "phone_number": "555-666-7788",
    "street_address": ["20 N San Mateo Dr"],
    "city": "San Mateo",
    "state": "CA",
    "postal_code": "94401",
    "country": "USA"
  },
  "identity": {
    "given_name": "John",
    "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": false,
    "is_politically_exposed": false,
    "immediate_family_exposed": false
  },
  "agreements": [
    {
      "agreement": "margin_agreement",
      "signed_at": "2020-09-11T18:09:33Z",
      "ip_address": "185.13.21.99"
    },
    {
      "agreement": "account_agreement",
      "signed_at": "2020-09-11T18:13:44Z",
      "ip_address": "185.13.21.99"
    },
    {
      "agreement": "customer_agreement",
      "signed_at": "2020-09-11T18:13:44Z",
      "ip_address": "185.13.21.99"
    }
  ],
  "documents": [
    {
      "document_type": "identity_verification",
      "document_sub_type": "passport",
      "content": "QWxwYWNhcyBjYW5ub3QgbGl2ZSBhbG9uZS4=",
      "mime_type": "image/jpeg"
    }
  ],
  "trusted_contact": {
    "given_name": "Jane",
    "family_name": "Doe",
    "email_address": "jane.doe@example.com"
  }
}

Parameters #

Attribute Requirement
contact
Required
identity
Required
disclosures
Required
documents
Optional
trusted_contact
Optional

Contact

Attribute Type Requirement Notes
email_address string
Required
phone_number string
Required
Phone number should include the country code, format: “+15555555555”
street_address string
Required
city string
Required
state string
Optional
required if country_of_tax_residency in identity model (below) is ‘USA’
postal_code string
Optional

Identity

Attribute Type Requirement Notes
given_name string
Required
family_name string
Required
date_of_birth date
Required
tax_id string
Optional
Required if tax_id_type is set.
tax_id_type ENUM.TaxIdType
Optional
Required if tax_id is set.
country_of_citizenship string
Optional
3 letter country code acceptable
country_of_birth string
Optional
3 letter country code acceptable
country_of_tax_residency string
Required
3 letter country code acceptable
funding_source ENUM.FundingSource
Required
annual_income_min string/number
Optional
annual_income_max string/number
Optional
liquid_net_worth_min string/number
Optional
liquid_net_worth_max string/number
Optional
total_net_worth_min string/number
Optional
total_net_worth_max string/number
Optional
extra object
Optional
Any additional information used for KYC purposes

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.

Attribute Type Requirement Notes
is_control_person boolean
Required
Whether user holds a controlling position in a publicly traded company, member of the board of directors or has policy making abilities in a publicly traded company.
is_affiliated_exchange_or_finra boolean
Required
is_politically_exposed boolean
Required
immediate_family_exposed boolean
Required
If your user’s immediate family member (sibling, husband/wife, child, parent) is either politically exposed or holds a control position.
employment_status ENUM.EmploymentStatus
Optional
employer_name string
Optional
employer_address string
Optional
employment_position string
Optional

Agreements

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

Attribute Type Requirement
[].agreement ENUM.DocumentType
Required
[].signed_at string (timestamp)
Required
[].ip_address string
Required

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 32MB.

    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

Attribute Type Required Notes
given_name string
Required
First name
family_name string
Required
Last name

In addition, only one of the following is required,

Attribute Type Required Notes
email_address string
Optional
phone_number string
Optional
street_address string
Optional
city string
Optional
If street_address is chosen
state string
Optional
If street_address is chosen
postal_code string
Optional
If street_address is chosen
country string
Optional
If street_address is chosen

Response #

Parameters #

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

Attribute Type Notes
id UUID UUID that identifies the account for later reference
account_number string A human-readable account number that can be shown to the end user
status enum.AccountStatus ENUM.AccountStatus
currency string Always USD
last_equity string EOD equity calculation (cash + long market value + short market value)
created_at string Format: YYYY-MM-DDTXX:YY:ZZ

Sample Response Body #

{
  "account": {
    "id": "0d18ae51-3c94-4511-b209-101e1666416b",
    "account_number": "9034005019",
    "status": "ACTIVE",
    "currency": "USD",
    "last_equity": "1500.65",
    "created_at": "2019-09-30T23:55:31.185998Z"
  }
}

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.


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": "johndoe@example.com",
    "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 #

Attribute Requirement
provider
Optional
kyc
Optional
document
Optional
photo
Optional
identity
Optional
watchlist
Optional

KYC

Attribute Type Notes
id string/UUID Your internal ID of check
risk_score int Overall risk score returned by KYC provider or assessed
risk_level string Overall risk level returned by KYC provider or assessed
risk_categories string The list of risk categories returned by the KYC provider or assessed
applicant_name string Given and family name of applicant
email_address string
nationality string
id_number string Government issued ID number of applicant
date_of_birth date
address string Concatenated street address, city, state and country of applicant
postal_code string
country_of_residency string
kyc_completed_at timestamp
ip_address string
check_initiated_at timestamp
check_completed_at timestamp
approval_status enum.CIPApprovalStatus ENUM: approved or rejected
approved_by string
approval_reason string
approved_at timestamp

Document

Attribute Type Notes
id string/UUID Your internal ID of check
result enum.CIPResult Overall result of specific check
status enum.CIPStatus Overall status of specific check
created_at timestamp
date_of_birth date
date_of_expiry date
document_numbers array Number of the document that was checked
document_type string Type of the document that was checked
first_name string First name extracted from the document
last_name string Last name extracted from the document
gender string
issuing_country string
nationality string
age_validation enum.CIPResult Checks whether the age calculated from the document’s date of birth data point is greater than or equal to the minimum accepted age set at account level
compromised_document enum.CIPResult Checks whether the image of the document has been found in our internal database of compromised documents
police_record enum.CIPStatus Checks whether the document has been identified as lost, stolen or otherwise compromised
data_comparison enum.CIPResult Checks whether data on the document is consistent with data provided when creating an applicant through the API
data_comparison_breakdown object example: {“date_of_birth”: “clear”, “date_of_expiry”: “clear” “document_numbers”: “clear”, “document_type”: “clear”, “first_name”: “clear”, “gender”: “clear”, “issuing_country”: “clear”, “last_name”: “clear”}
image_integrity enum.CIPResult Checks whether the document was of sufficient quality to verify
image_integrity_breakdown object example: {“colour_picture”: “clear”, “conclusive_document_quality”: “clear”, “image_quality”: “clear”, “supported_document”: “clear”}
visual_authenticity object Checks whether visual (non-textual) elements are correct given the document type. Example: {“digital_tampering”: “clear”, “face_detection”: “clear”, “fonts”: “clear”, “original_document_present”: “clear”, “picture_face_integrity”: “clear”, “security_features”: “clear”, “template”: “clear”}

Photo

Attribute Type Notes
id string/UUID Your internal ID of check
result enum.CIPResult Overall result of specific check
status enum.CIPStatus Overall status of specific check
created_at timestamp
face_comparison enum.CIPResult Checks whether the face in the document matches the face in the live photo
face_comparison_breakdown object {“face_match”:{“result”: “clear”,“properties”:{“score”: “80”}}}
image_integrity enum.CIPResult Checks whether the quality and integrity of the uploaded files were sufficient to perform a face comparison
image_integrity_breakdown string example: {“face_detected”:{“result”: “clear”},“source_integrity”: {“result”: “clear”}}
visual_authenticity enum.CIPResult Checks whether the person in the live photo is real (not a spoof)
visual_authenticity_breakdown string {“spoofing_detection”: {“result”: “clear”,“properties”: {“score”: “26”}}}}

Identity

Attribute Type Notes
id string/UUID Your internal ID of check
result enum.CIPResult Overall result of specific check
status enum.CIPStatus Overall status of specific check
created_at timestamp
matched_address enum.CIPResult Represents the matched address for the applicant
matched_addresses object example: [{“id”: “19099121”,“match_types”:[“credit_agencies”,“voting_register”]}]
sources enum.CIPResult Shows the total number of sources found for applicant’s identity
sources_breakdown object example: {“total_sources”: {“result”: “clear”,“properties”: {“total_number_of_sources”: “3”}}}
address enum.CIPResult Result if it was cleared against a data source
address_breakdown object example: {“credit_agencies”: {“result”: “clear”,“properties”:{“number_of_matches”:“1”}}
date_of_birth enum.CIPResult Result if it was cleared against a data source
date_of_birth_breakdown object example: {“credit_agencies”:{“result”: “clear”,“properties”: {“number_of_matches”: “1”}}

Watchlist

Attribute Type Notes
id string/UUID Your internal ID of check
result enum.CIPResult Overall result of specific check
status enum.CIPStatus Overall status of specific check
created_at timestamp
records object [{“text”: “Record info”}]
politically_exposed_person enum.CIPResult
sanction enum.CIPResult
adverse_media enum.CIPResult
monitored_lists enum.CIPResult

Enums #

CIP Result #

Attribute Description
clear If all underlying verifications pass, the result is clear
consider If the check has returned information that needs to be evaluated, the result is consider

CIP Status #

Attribute Description
complete Check is done
withdrawn Check has been cancelled

CIP Provider #

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

Attribute Description
trulioo
onfido
veriff
jumio
getmati
alloy

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",
    "capacity_acting": "SELF",
    "country_citizen": "Australia",
    "date": "2021-06-14",
    "date_of_birth": "1970-01-01",
    "foreign_tax_id": "123 456 789",
    "full_name": "John Doe",
    "ip_address": "127.0.0.1",
    "mailing_address_city_state": "Adelaide",
    "mailing_address_country": "Australia",
    "mailing_address_street": "51 Main St",
    "paragraph_number": "15",
    "percent_rate_withholding": 5.0,
    "permanent_address_city_state": "Adelaide",
    "permanent_address_country": "Australia",
    "permanent_address_street": "20 Main St",
    "reference_number": "abc123",
    "residency": "Australia",
    "revision": "7-2017",
    "tax_id_ssn": "123-00-456",
    "timestamp": "2021-06-14T09:31:05Z",
    "income_type": "interest",
    "signer_full_name": "Mr. Signing User"
  }
}

Parameters #

Attribute Type Requirement Notes
additional_conditions string
Optional
capacity_acting string
Optional
country_citizen string
Required
date date
Required
Format YYYY-MM-DD
date_of_birth date
Required
Format YYYY-MM-DD
foreign_tax_id string
Optional
full_name string
Required
income_type string
Optional
ip_address string
Required
mailing_address_city_state string
Optional
mailing_address_country string
Optional
mailing_address_street string
Optional
paragraph_number string
Optional
percent_rate_withholding string (decimal)
Optional
permanent_address_city_state string
Required
permanent_address_country string
Required
permanent_address_street string
Required
reference_number string
Optional
residency string
Optional
revision string
Required
“7-2017” until the IRS releases an updated version of the form
signer_full_name string
Required
tax_id_ssn string
Optional
timestamp string (timestamp)
Required

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 #
Attribute Type Required Notes
query string
Optional
Pass space-delimited tokens. The response will contain accounts that match with each of the tokens (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_after string, timestamp
Optional
created_before string, timestamp
Optional
status ENUM.AccountStatus
Optional
ENUM.AccountStatus
sort string
Optional
asc or desc. Defaults to desc
entities string
Optional
Comma-delimited entity names to include in the response

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.


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",
  "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",
  "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 #

Attribute Type Notes
id string/uuid The account ID
account_number string The account number
status ENUM.AccountStatus The current status of the account
currency string Always USD
buying_power string/number Current available cash buying power. If multiplier = 2 then buying_power = max(equity-initial_margin(0) * 2). If multiplier = 1 then buying_power = cash.
regt_buying_power string/number User’s buying power under Regulation T (excess equity - (equity - margin value) - * margin multiplier)
daytrading_buying_power string/number Your buying power for day trades (continuously updated value)
cash string/number Cash balance
cash_withdrawable string/number Cash available for withdrawal
cash_transferable string/number Cash available for transfer (JNLC)
pending_transfer_out string/number Cash pending transfer out
portfolio_value string/number Total value of cash + holding positions. (This field is deprecated. It is equivalent to the equity field.)
pattern_day_trader boolean Whether account is flagged as pattern day trader or not.
trading_blocked boolean If true, the account is not allowed to place orders.
transfers_blocked boolean If true, the account is not allowed to request money transfers.
account_blocked boolean If true, the account activity by user is prohibited.
created_at boolean Timestamp this account was created at
trade_suspended_by_user string/number If true, the account is not allowed to place orders.
multiplier string/number “1” or “2”
shorting_enabled boolean Flag to denote whether or not the account is permitted to short
equity string/number cash + long_market_value + short_market_value
last_equity string/number Equity as of previous trading day at 16:00:00 ET
long_market_value string/number Real-time MtM value of all long positions held in the account
short_market_value string/number Real-time MtM value of all short positions held in the account
initial_margin string/number Reg T initial margin requirement (continuously updated value)
maintenance_margin string/number Maintenance margin requirement (continuously updated value)
last_maintenance_margin string/number Maintenance margin requirement on the previous trading day
sma string/number Value of Special Memorandum Account (will be used at a later date to provide additional buying_power)
daytrade_count number The current number of daytrades that have been made in the last 5 trading days (inclusive of today)
previous_close string/timedate Previous sessions close time
last_long_market_value string/number Value of all long positions as of previous trading day at 16:00:00 ET
last_short_market_value string/number Value of all short positions as of previous trading day at 16:00:00 ET
last_cash string/number Value of all cash as of previous trading day at 16:00:00 ET
last_initial_margin string/number Value of Reg T margin as of previous trading day at 16:00:00 ET
last_regt_buying_power string/number Value of Reg T buying power as of previous trading day at 16:00:00 ET
last_daytrading_buying_power string/number Value of daytrading buying power as of previous trading day at 16:00:00 ET
last_daytrade_count string/number Value of daytrade count as of previous trading day at 16:00:00 ET
clearing_broker string/number Clearing broker

Updating an Account #

PATCH /v1/accounts/{account_id}

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

Request #

Parameters #

Contact

Attribute Key Required Notes
email_address [].contact
Optional
Email addresses should be verified prior to using this operation to update them
phone_number [].contact
Optional
street_address [].contact
Optional
city [].contact
Optional
state [].contact
Optional
postal_code [].contact
Optional
  • 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) support@alpaca.markets

Identity

Attribute Key Required Notes
funding_source [].identity
Optional
annual_income_min [].identity
Optional
annual_income_max [].identity
Optional
liquid_net_worth_min [].identity
Optional
liquid_net_worth_max [].identity
Optional
total_net_worth_min [].identity
Optional
total_net_worth_max [].identity
Optional

Disclosures

Attribute Key Required Notes
is_control_person [].disclosures
Optional
is_affiliated_exchange_or_finra [].disclosures
Optional
is_politically_exposed [].disclosures
Optional
immediate_family_exposed [].disclosures
Optional
employment_status [].disclosures
Optional
employer_name [].disclosures
Optional
employer_address [].disclosures
Optional
employment_position [].disclosures
Optional

Trusted Contact

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

Attribute Type Required Notes
given_name string
Required
First name
family_name string
Required
Last name

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

Attribute Type Required Notes
email_address string
Optional
phone_number string
Optional
street_address string
Optional
city string
Optional
If street_address is chosen
state string
Optional
If street_address is chosen
postal_code string
Optional
If street_address is chosen
country string
Optional
If street_address is chosen

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.


Deleting an Account #

DELETE /v1/accounts/{account_id}

This operation closes an active account.

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