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.

Attribute Type Notes
id string (UUID) Account Identifier
account_number string A human-readable account number that can be shown to the end user
status string<ENUM.AccountStatus> Status of account equity trading
crypto_status string<ENUM.CryptoStatus> Status of account crypto trading
currency string Currency associated to account (By default and typically USD)
last_equity string End of day (EOD) equity calculation (cash + long market value + short market value)
account_type string <ENUM.AccountType> Type of account
trading_configurations object «TradingConfigurations» Trading configurations associated to account. Field is nullable.
created_at string «timestamp» Timestamp (RFC3339) of account creation.
kyc_results object «KYCResult» KYC results associated to user account
enabled_assets array«ENUM.EnabledAssets» Assets the user has enabled and is able to trade once status and/or crypto_status are ACTIVE
contact object«Contact» Contact information about the user
identity object «Identity» KYC information about the user
disclosures object «Disclosures» Required disclosures about the user
documents array «Documents» Any documents that need to be uploaded (eg. passport, visa, …)
agreements array «Agreements» Agreements required to be signed by the user to open their account
trusted_contact object«TrustedContact» The contact information of a trusted contact to the user in case account recovery is needed.

Enabled Assets #

Attribute Type
enabled_assets array of ENUM.AssetClass

Contact #

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

Identity #

Attribute Type
given_name string
middle_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
visa_type ENUM.VisaType
visa_expiration_date date
date_of_departure_from_usa date
permanent_resident boolean
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
context array of DisclosureContext
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.Agreements
[].signed_at string (timestamp)
[].ip_address string
[].revision 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 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

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 #

Asset Class #

Attribute Description
us_equity U.S. Equities
crypto Cryptocurrencies

Account Type #

Attribute Description
trading Typical brokerage account
custodial Trading account opened on behalf of a minor and ownership will be transferred to the minor when they reach the age of majority
donor_advised Trading account established at a public charity which allows donors to receive tax benefits from their charitable contributions

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
IDN_KTP Indonesia KTP
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
PAK_NIC Pakistan National Identity Card 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

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.

Attribute Description
B1 USA Visa Category B-1
B2 USA Visa Category B-2
DACA USA Visa Category DACA
E1 USA Visa Category E-1
E2 USA Visa Category E-2
E3 USA Visa Category E-3
F1 USA Visa Category F-1
G4 USA Visa Category G-4
H1B USA Visa Category H-1B
J1 USA Visa Category J-1
L1 USA Visa Category L-1
OTHER Any other USA Visa Category
O1 USA Visa Category O-1
TN1 USA Visa Category TN-1

Employment Status #

Attribute Description
UNEMPLOYED Unemployed
EMPLOYED Employed
STUDENT Student
RETIRED Retired

Context Type #

Attribute Description
CONTROLLED_FIRM Controlled firm. Recommened to use when is_control_person = true
AFFILIATE_FIRM Affiliated firm. Recommened to use when is_affiliated_exchange_or_finra = true
IMMEDIATE_FAMILY_EXPOSED Immediate family exposed. Recommended to use when immediate_family_exposed = true

Agreements #

Attribute Description
customer_agreement Customer agreement
crypto_agreement Crypto 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
w9 W9 tax form

Account Status #

Attribute Description
INACTIVE Account not enabled to trade equities
ONBOARDING The account has been created but we haven’t performed KYC yet. This is only used with Onfido.
SUBMITTED Application has been submitted and in process of review
ACTION_REQUIRED Application requires manual action
EDITED Application was edited (e.g. to match info from uploaded docs). This is a transient status.
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 Equities account is fully active and can start trading
SUBMISSION_FAILED Account submissions has failed
DISABLED Account is disabled, comes after ACTIVE
ACCOUNT_UPDATED Account has been updated
ACCOUNT_CLOSED Account is closed

Crypto Status #

Attribute Description
INACTIVE Account not enabled to trade crypto
ONBOARDING The account has been created but we haven’t performed KYC yet. This is only used with Onfido.
SUBMITTED Application has been submitted and in process of review
ACTION_REQUIRED Application requires manual action
EDITED Application was edited (e.g. to match info from uploaded docs). This is a transient status.
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 Crypto account is active and can start trading
SUBMISSION_FAILED Account submissions has failed
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 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.

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

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

Enabled Assets

Attribute Type Requirement Notes
enabled_assets array of ENUM.AssetClass
Optional
Will default to us_equity. Alpaca has the ability to update the default value upon request.

Contact

Attribute Type Requirement Notes
email_address string
Required
phone_number string
Required
Phone number should include the country code, format: “+15555555555”
street_address array of strings
Required
Maximum of 3 objects in array
unit string
Optional
The specific apartment number if applicable
city string
Required
state string
Optional
required if country_of_tax_residence in identity model (below) is ‘USA’
postal_code string
Optional

Identity

Attribute Type Requirement Notes
given_name string
Required
middle_name string
Optional
family_name string
Required
date_of_birth date
Required
Format: YYYY-MM-DD
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_residence string
Required
3 letter country code acceptable
visa_type ENUM.VisaType
Optional
Only used to collect visa types for users residing in the USA.
visa_expiration_date date
Optional
Required if visa_type is set.
date_of_departure_from_usa date
Optional
Required if visa_type = B1 or B2
permanent_resident boolean
Optional
Only used to collect permanent residence status in the USA.
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.
context array of DisclosureContext
Optional
Information relevant to the user’s disclosure selection should be sent through this object.
employment_status ENUM.EmploymentStatus
Optional
employer_name string
Optional
employer_address string
Optional
employment_position string
Optional

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.

Attribute Type Requirement Notes
context_type ENUM.ContextType
Required
company_name string
Required
if context_type = AFFILIATE_FIRM or CONTROLLED_FIRM
company_street_address string
Required
if context_type = AFFILIATE_FIRM or CONTROLLED_FIRM
company_city string
Required
if context_type = AFFILIATE_FIRM or CONTROLLED_FIRM
company_state string
Required
if company_country = USA
company_country string
Required
if context_type = AFFILIATE_FIRM or CONTROLLED_FIRM
company_compliance_email string
Required
if context_type = AFFILIATE_FIRM or CONTROLLED_FIRM
given_name string
Required
if context_type = IMMEDIATE_FAMILY_EXPOSED
family_name string
Required
if context_type = IMMEDIATE_FAMILY_EXPOSED

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.Agreements
Required
[].signed_at string (timestamp)
Required
[].ip_address string
Required
[].revision string
Optional

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

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
account_type string <ENUM.AccountType> Type of account
status enum.AccountStatus ENUM.AccountStatus
crypto_status enum.CryptoStatus ENUM.CryptoStatus
currency string Always USD
last_equity string EOD equity calculation (cash + long market value + short market value)
created_at string «timestamp» Timestamp (RFC3339) of account creation.
enabled_assets array«ENUM.EnabledAssets» Assets the user has enabled and is able to trade once status and/or crypto_status are ACTIVE
contact object«Contact» Contact information about the user
identity object «Identity» KYC information about the user
disclosures object «Disclosures» Required disclosures about the user
documents array «Documents» Any documents that need to be uploaded (eg. passport, visa, …)
agreements array «Agreements» Agreements required to be signed by the user to open their account
trusted_contact object«TrustedContact» The contact information of a trusted contact to the user in case account recovery is needed.

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 #

Attribute Type Requirement Notes
referrer URI encoded string
Optional
The referrer URL of your web app or the application ID of your mobile app. If not passed in, will default to the * wildcard
platform ENUM.Platform
Optional
Required if referrer provided. Enum values are either mobile or web

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 #

Attribute Type Requirement Notes
outcome ENUM.Outcome
Required
The result of the SDK flow
reason string
Optional
Any additional information related to the outcome
token string/JWT
Required
The SDK token associated with the SDK flow you are updating the outcome for

Enums #

Outcome #
Attribute Description
NOT_STARTED The user has not started the SDK flow yet. outcome is set to this default value upon token generation
USER_EXITED The user exited the SDK flow
SDK_ERROR An error occurred in the SDK flow
USER_COMPLETED The user completed the SDK flow

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 #

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

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 #

Attribute Type Requirement Notes
additional_conditions string
Optional
capacity_acting string
Optional
Unique to revision “7-2017”
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
ftin_not_required boolean
Optional
Required if foreign_tax_id and tax_id_ssn are empty
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
“10-2021” 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
Inclusive of timestamp. Example: 2019-10-12T07:20:50.52Z
created_before string, timestamp
Optional
Inclusive of timestamp. Example: 2019-10-12T07:20:50.52Z
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.

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 #

Attribute Type Notes
id string/uuid The account ID
admin_configurations object «AdminConfigurations» Account settings set by Alpaca Admins
account_number string The account number
status ENUM.AccountStatus The current status of the account
crypto_status ENUM.CryptoStatus The current status of the crypto enablement
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

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.

Attribute Type Notes
restrict_to_liquidation_reasons object«RestrictToLiquidationReasons» Reasons why the liquidation only flag was set
outgoing_transfers_blocked bool Wire-out transfers blocked for the account if false
incoming_transfers_blocked bool Deposits are blocked for the account if false
disable_shorting bool If true the account is not allowed to create short position orders
disable_fractional bool If true, the account cannot create orders for fractional share positions
disable_crypto bool If true, the account is not allowed to trade cryptos
disable_day_trading bool If true, the account is not allowed to day trade (e.g. buy and sell the same security on the same day)
max_margin_multiplier int Max margin multipler is set by admin to this value
acct_daily_transfer_limit int Override the correspondent level daily transfer limits
RestrictToLiquidationReasons #
Attribute Type Notes
pattern_day_trading bool Set when the trading account is marked as a PDT, but its equity falls below the $25k treshold
ach_return bool Set when an incoming ACH transfer gets rejected
position_to_equity_ratio bool Set when the position to equity ration exceeds the maximum limit
unspecified bool Default value for unknown reason

Updating an Account #

PATCH /v1/accounts/{account_id}

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

Request #

Parameters #

Enabled Assets

Attribute Type Requirement Notes
enabled_assets array of ENUM.AssetClass
Optional
Must patch ["us_equity", "crypto"] along with the crypto agreement to enable crypto for an existing user with access only to equities.

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
unit [].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) [email protected]

Identity

Attribute Key Required Notes
given_name [].identity
Optional
Name can only be updated once via API request.
middle_name [].identity
Optional
Name can only be updated once via API request.
family_name [].identity
Optional
Name can only be updated once via API request.
visa_type [].identity
Optional
Only used to collect visa types for users residing in the USA.
visa_expiration_date [].identity
Optional
Required if visa_type is set.
date_of_departure_from_usa [].identity
Optional
Required if visa_type = B1 or B2
permanent_resident [].identity
Optional
Only used to collect permanent residence status in the USA.
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.


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

 

Edit Edit this page