Alpaca Accounts API
The Accounts API from Alpaca — 14 operation(s) for accounts.
OpenAPI Specification
openapi: 3.0.0
info:
title: Broker Account Activities Accounts API
description: Open brokerage accounts, enable crypto and stock trading, and manage the ongoing user experience with Alpaca Broker API
version: 1.0.0
contact:
name: Alpaca Support
email: support@alpaca.markets
url: https://alpaca.markets/support
termsOfService: https://s3.amazonaws.com/files.alpaca.markets/disclosures/library/TermsAndConditions.pdf
servers:
- url: https://broker-api.sandbox.alpaca.markets
description: Sandbox endpoint
- url: https://broker-api.alpaca.markets
description: Production endpoint
security:
- BasicAuth: []
tags:
- name: Accounts
paths:
/v1/accounts:
get:
tags:
- Accounts
summary: Get all accounts
parameters:
- name: query
in: query
schema:
type: string
description: 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).
- schema:
type: string
format: date-time
in: query
name: created_after
- schema:
type: string
format: date-time
in: query
name: created_before
- schema:
type: string
in: query
name: status
description: See the AccountStatus model for values
- $ref: '#/components/parameters/Sort'
- schema:
type: string
in: query
name: entities
description: Comma-delimited entity names to include in the response
responses:
'200':
description: 'The response is a list of Account model up to 1000 items
per query order by created_at. To scroll the result,
please use the created_after parameter.
'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Account'
operationId: getAllAccounts
description: Retrieves all accounts found by the query'
post:
tags:
- Accounts
summary: Create an account
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCreationRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
'400':
description: The post body is not well formed.
content:
application/json:
schema:
type: string
'409':
description: There is already an existing account registered with the same email address.
'422':
description: One of the input values is not a valid value.
content:
application/json:
schema:
type: string
operationId: createAccount
description: '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. '
/v1/accounts/{account_id}:
parameters:
- $ref: '#/components/parameters/AccountID'
get:
summary: Get an account by Id.
tags:
- Accounts
description: '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.
'
responses:
'200':
description: Will return an AccountExtended if an account with account_id exists, otherwise will throw an error.
content:
application/json:
schema:
$ref: '#/components/schemas/AccountExtended'
operationId: getAccount
patch:
tags:
- Accounts
summary: Update an account
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountUpdateRequest'
responses:
'200':
description: If all parameters are valid and updates have been made, it returns with status code 200. The response is the account model.
content:
application/json:
schema:
$ref: '#/components/schemas/AccountExtended'
'400':
description: The post body is not well formed.
content:
application/json:
schema:
type: string
'422':
description: The request body contains an attribute that is not permitted to be updated or you are attempting to set an invalid value.
content:
application/json:
schema:
type: string
operationId: patchAccount
description: 'This operation updates account information.
If all parameters are valid and updates have been made, it returns with status code 200. The response is the account model.'
delete:
summary: Request to close an account
tags:
- Accounts
responses:
'204':
description: No content.
operationId: deleteAccount
description: This operation closes an active account.
/v1/accounts/{account_id}/documents/upload:
parameters:
- $ref: '#/components/parameters/AccountID'
post:
tags:
- Accounts
summary: Upload a document to an already existing account
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentUploadRequest'
responses:
'204':
description: Success (No Content)
'400':
description: Bad Request. The body in the request is not valid.
content:
application/json:
schema:
type: string
'404':
description: Not Found. No account was found for this account_id
content:
application/json:
schema:
type: string
operationId: uploadDocToAccount
description: 'Upload a document to be attached to an account.
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.'
/v1/accounts/{account_id}/recipient_banks:
parameters:
- $ref: '#/components/parameters/AccountID'
get:
tags:
- Accounts
summary: Retrieve bank relationships for an account
parameters:
- name: status
in: query
schema:
type: string
enum:
- ACTIVE
- INACTIVE
example: ACTIVE
- name: bank_name
in: query
schema:
type: string
responses:
'200':
description: Success. Returns the bank relationship model.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Bank'
'400':
description: Bad request. The body in the request is not valid.
operationId: getRecipientBanks
description: Retrieves Bank Relationships for an account
post:
tags:
- Accounts
summary: Create a Bank Relationship for an account
parameters:
- $ref: '#/components/parameters/AccountID'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBankRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Bank'
'400':
description: Bad Request
'409':
description: Conflict
operationId: createRecipientBank
description: If successful, retrieves Bank Relationships for an account
/v1/accounts/{account_id}/recipient_banks/{bank_id}:
parameters:
- $ref: '#/components/parameters/AccountID'
- name: bank_id
in: path
required: true
schema:
type: string
format: uuid
delete:
tags:
- Accounts
summary: Delete a Bank Relationship for an account
responses:
'204':
description: Success (No Content)
'400':
description: Bad Request
'404':
description: Bank Not Found
operationId: deleteRecipientBank
description: If successful, deletes Bank Relationship for an account
/v1/accounts/{account_id}/transfers:
parameters:
- $ref: '#/components/parameters/AccountID'
get:
summary: Return a list of transfers for an account.
tags:
- Accounts
description: 'You can query a list of transfers for an account.
You can filter requested transfers by values such as direction and status.
'
parameters:
- name: direction
in: query
schema:
enum:
- INCOMING
- OUTGOING
type: string
description: INCOMING or OUTGOING
- name: limit
in: query
schema:
type: integer
format: int32
- name: offset
in: query
schema:
type: integer
format: int32
responses:
'200':
description: Success.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Transfer'
examples:
example-1:
value:
- id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
relationship_id: 81412018-ffa2-43f9-a3eb-d39f1c5e0f87
bank_id: f1ae96de-94c1-468e-93a3-6b7213930ca8
account_id: 449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65
type: ach
status: QUEUED
reason: string
amount: string
direction: INCOMING
created_at: '2019-08-24T14:15:22Z'
updated_at: '2019-08-24T14:15:22Z'
expires_at: '2019-08-24T14:15:22Z'
additional_information: string
example-2:
value:
- id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
relationship_id: 81412018-ffa2-43f9-a3eb-d39f1c5e0f87
bank_id: f1ae96de-94c1-468e-93a3-6b7213930ca8
account_id: 449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65
type: ach
status: QUEUED
reason: string
amount: string
direction: INCOMING
created_at: '2019-08-24T14:15:22Z'
updated_at: '2019-08-24T14:15:22Z'
expires_at: '2019-08-24T14:15:22Z'
additional_information: string
operationId: getTransfersForAccount
post:
summary: Request a new transfer
tags:
- Accounts
description: 'Create a new transfer to an account to fund it.
In the sandbox environment, you can instantly deposit to or withdraw from an account with a virtual money amount. In the production environment, this endpoint is used only for requesting an outgoing (withdrawal) wire transfer at this moment. For the wire transfer (in production), you need to create a bank resource first using the Bank API. For more on how to fund an account in sandbox please check out this tutorial [here](https://alpaca.markets/learn/fund-broker-api/).'
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTransferRequest'
responses:
'200':
description: Successfully requested a transfer.
content:
application/json:
schema:
$ref: '#/components/schemas/Transfer'
operationId: createTransferForAccount
/v1/accounts/{account_id}/transfers/{transfer_id}:
parameters:
- $ref: '#/components/parameters/AccountID'
- schema:
type: string
format: uuid
name: transfer_id
in: path
required: true
description: Tranfer identifier
delete:
summary: Request to close a transfer
operationId: deleteTransfer
responses:
'204':
description: Success (No Content)
'404':
$ref: '#/components/responses/NotFound'
description: Request to close a transfer
tags:
- Accounts
/v1/accounts/activities:
get:
tags:
- Accounts
summary: Retrieve account activities
parameters:
- name: account_id
in: query
schema:
type: string
format: uuid
description: id of a single account to filter by
- name: date
in: query
schema:
type: string
description: Both formats YYYY-MM-DD and YYYY-MM-DDTHH:MM:SSZ supported.
- name: until
in: query
schema:
type: string
description: Both formats YYYY-MM-DD and YYYY-MM-DDTHH:MM:SSZ supported.
- name: after
in: query
schema:
type: string
description: Both formats YYYY-MM-DD and YYYY-MM-DDTHH:MM:SSZ supported. Cannot be used with date.
- $ref: '#/components/parameters/Direction'
- name: page_size
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The maximum number of entries to return in the response
- in: query
name: page_token
description: 'The Activity ID of the end of your current page of results. '
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Activity'
operationId: getAccountActivities
description: "Returns an array of Activities\n\nNotes:\n* Pagination is handled using the `page_token` and `page_size` parameters.\n* `page_token` represents the ID of the end of your current page of results.\n for example if in your first response the id of the last Activiy item returned in the array was `20220203000000000::045b3b8d-c566-4bef-b741-2bf598dd6ae7`, you'd pass that value as `page_token` to get the next page of results\n\n* If specified with a `direction` of `desc`, for example, the results will end before the activity with the specified ID.\n* If specified with a `direction` of `asc`, results will begin with the activity immediately after the one specified.\n* `page_size` is the maximum number of entries to return in the response.\n* If `date` is not specified, the default and maximum value is 100.\n* If `date` is specified, the default behavior is to return all results, and there is no maximum page size."
/v1/accounts/activities/{activity_type}:
parameters:
- $ref: '#/components/parameters/ActivityType'
get:
tags:
- Accounts
parameters:
- name: account_id
in: query
schema:
type: string
format: uuid
description: id of a single account to filter by
- name: date
in: query
schema:
type: string
format: date-time
description: Both formats YYYY-MM-DD and YYYY-MM-DDTHH:MM:SSZ supported.
- name: until
in: query
schema:
type: string
format: date-time
description: Both formats YYYY-MM-DD and YYYY-MM-DDTHH:MM:SSZ supported.
- name: after
in: query
schema:
type: string
format: date-time
description: Both formats YYYY-MM-DD and YYYY-MM-DDTHH:MM:SSZ supported.
- $ref: '#/components/parameters/Direction'
- name: page_size
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The maximum number of entries to return in the response
- name: page_token
in: query
schema:
type: string
description: The ID of the end of your current page of results
summary: Retrieve specific account activities
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Activity'
operationId: getAccountActivitiesByType
description: "Retrieves an Array of Activies by type\n\nNotes:\n* Pagination is handled using the `page_token` and `page_size` parameters.\n* `page_token` represents the ID of the end of your current page of results.\n for example if in your first response the id of the last Activiy item returned in the array was `20220203000000000::045b3b8d-c566-4bef-b741-2bf598dd6ae7`, you'd pass that value as `page_token` to get the next page of results\n\n* If specified with a `direction` of `desc`, for example, the results will end before the activity with the specified ID.\n* If specified with a `direction` of `asc`, results will begin with the activity immediately after the one specified.\n* `page_size` is the maximum number of entries to return in the response.\n* If `date` is not specified, the default and maximum value is 100.\n* If `date` is specified, the default behavior is to return all results, and there is no maximum page size."
/v1/accounts/{account_id}/ach_relationships:
parameters:
- $ref: '#/components/parameters/AccountID'
get:
summary: Retrieve ACH Relationships for an account
tags:
- Accounts
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ACHRelationship'
operationId: getAccountACHRelationships
description: Returns a list of ACH Relationships for an account
parameters:
- schema:
type: string
in: query
name: statuses
description: Comma-separated status values
post:
summary: Create an ACH Relationship
operationId: createACHRelationshipForAccount
responses:
'200':
description: returns the newly created ACH Relationship entity.
content:
application/json:
schema:
$ref: '#/components/schemas/ACHRelationship'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/NotAuthorized'
'409':
description: The account already has an active relationship.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: 'Create a new ACHRelationship for an account
If successful, will return 200 code with a newly created ACH Relationship entity.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateACHRelationshipRequest'
description: 'Create ACH Relationship '
tags:
- Accounts
/v1/accounts/{account_id}/ach_relationships/{ach_relationship_id}:
parameters:
- $ref: '#/components/parameters/AccountID'
- schema:
type: string
format: uuid
name: ach_relationship_id
in: path
description: ACH relationship identifier
required: true
delete:
summary: Delete an existing ACH relationship
operationId: deleteACHRelationshipFromAccount
responses:
'204':
description: Success (No Content)
'400':
description: the passed in account_id or relationship_id were invalid
'404':
$ref: '#/components/responses/NotFound'
description: Delete an existing ACH relationship for an account
tags:
- Accounts
/v1/trading/accounts/{account_id}/account:
parameters:
- $ref: '#/components/parameters/AccountID'
get:
operationId: getTradingAccount
summary: Retrieve trading details for an account.
tags:
- Accounts
description: 'As a broker you can view more trading details about your users.
The response is a Trading Account model.'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TradeAccount'
/v1/events/accounts/status:
get:
summary: Subscribe to account status events (SSE).
tags:
- Accounts
description: 'Events API provide event push as well as historical queries via SSE (server sent events).
Historical events are streamed immediately if queried, and updates are pushed as events occur.
Query Params Rules:
- `since` required if `until` specified
- `since_id` required if `until_id` specified
- `since` and `since_id` can’t be used at the same time
Behavior:
- if `since` or `since_id` not specified this will not return any historic data
- if `until` or `until_id` reached stream will end (status 200)
---
Note for people using the clients generated from this OAS spec. Currently OAS-3 doesn''t have full support for representing SSE style responses from an API, so if you are using a generated client and don''t specify a `since` and `until` there is a good chance the generated clients will hang waiting for the response to end.
If you require the streaming capabilities we recommend not using the generated clients for this specific usecase until the OAS-3 standards come to a consensus on how to represent this correcting in OAS-3.
'
parameters:
- name: since
in: query
schema:
type: string
format: date
description: 'Format: YYYY-MM-DD'
- name: until
in: query
schema:
type: string
format: date
description: 'Format: YYYY-MM-DD'
- name: since_id
in: query
schema:
type: integer
- name: until_id
in: query
schema:
type: integer
responses:
'200':
description: Connected. Events will now start streaming as long as you keep the connection open.
content:
text/event-stream:
schema:
type: array
items:
$ref: '#/components/schemas/AccountStatusEvent'
examples: {}
operationId: suscribeToAccountStatusSSE
/v2/account:
get:
summary: Get account
tags:
- Accounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Account_2'
operationId: getAccount
parameters: []
description: Returns the account associated with the API key.
components:
schemas:
Transfer:
title: Transfer
type: object
x-examples:
example-1:
id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
relationship_id: 81412018-ffa2-43f9-a3eb-d39f1c5e0f87
bank_id: f1ae96de-94c1-468e-93a3-6b7213930ca8
account_id: 449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65
type: ach
status: QUEUED
reason: string
amount: string
direction: INCOMING
created_at: '2019-08-24T14:15:22Z'
updated_at: '2019-08-24T14:15:22Z'
expires_at: '2019-08-24T14:15:22Z'
additional_information: string
description: 'Transfers allow you to transfer money/balance into your end customers'' account (deposits) or out (withdrawal).
[Main docs here](https://alpaca.markets/docs/api-references/broker-api/funding/transfers/#the-transfer-object)'
properties:
id:
type: string
format: uuid
description: The transfer ID
relationship_id:
type: string
format: uuid
description: The ACH relationship ID only present if type = "ach"
bank_id:
type: string
format: uuid
description: The ID of the Bank, only present if type = "wire"
account_id:
type: string
format: uuid
description: The account ID
type:
$ref: '#/components/schemas/TransferType'
status:
$ref: '#/components/schemas/TransferStatus'
reason:
type: string
description: Cause of the status
nullable: true
amount:
type: string
description: Must be > 0.00
format: decimal
direction:
$ref: '#/components/schemas/TransferDirection'
created_at:
type: string
format: date-time
description: Timedate when transfer was created
updated_at:
type: string
format: date-time
description: Timedate when transfer was updated
expires_at:
type: string
format: date-time
description: Timedate when transfer was expired
additional_information:
type: string
description: Additional information. Only applies when type = "wire".
nullable: true
hold_until:
type: string
format: date-time
instant_amount:
type: string
required:
- id
- account_id
- type
- status
- amount
- direction
- created_at
TransferDirection:
type: string
example: INCOMING
enum:
- INCOMING
- OUTGOING
description: '- **INCOMING**
Funds incoming to user’s account (deposit).
- **OUTGOING**
Funds outgoing from user’s account (withdrawal).
'
AccountExtended:
type: object
description: Represents an account with all data available. If your api response is missing some of these fields, there is a good chance you are using a route that returns `Account` instances instead of these.
x-examples:
example-1:
id: 3dcb795c-3ccc-402a-abb9-07e26a1b1326
account_number: '601842165'
status: ACTIVE
crypto_status: PAPER_ONLY
currency: USD
last_equity: '40645.13'
created_at: '2022-01-21T21:25:26.583576Z'
contact:
email_address: strange_elbakyan_97324509@example.com
phone_number: 614-555-0697
street_address:
- 20 N San Mateo Dr
city: San Mateo
state: CA
postal_code: '94401'
identity:
given_name: Strange
family_name: Elbakyan
date_of_birth: '1970-01-01'
tax_id_type: USA_SNN
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: margin_agreement
signed_at: '2022-01-21T21:25:26.579487214Z'
ip_address: 127.0.0.1
revision: null
- agreement: customer_agreement
signed_at: '2022-01-21T21:25:26.579487214Z'
ip_address: 127.0.0.1
revision: null
- agreement: account_agreement
signed_at: '2022-01-21T21:25:26.579487214Z'
ip_address: 127.0.0.1
revision: null
documents:
- document_type: identity_verification
document_sub_type: passport
id: d5af1585-6c60-494d-9ea5-c5df62704229
content: https://s3.amazonaws.com/example/documents/accounts/PRESIGNED-EXAMPLE.jpg
created_at: '2022-01-21T21:25:28.184231Z'
trusted_contact:
given_name: Jane
family_name: Doe
email_address: strange_elbakyan_97324509@example.com
account_type: trading
trading_configurations: null
properties:
id:
type: string
format: uuid
account_number:
type: string
nullable: true
status:
$ref: '#/components/schemas/AccountStatus'
crypto_status:
$ref: '#/components/schemas/AccountStatus'
kyc_result:
$ref: '#/components/schemas/KYCResult'
currency:
type: string
description: Always "USD"
example: USD
last_equity:
type: string
format: decimal
created_at:
type: string
format: date-time
contact:
$ref: '#/components/schemas/Contact'
identity:
$ref: '#/components/schemas/Identity'
disclosures:
$ref: '#/components/schemas/Disclosures'
agreements:
type: array
items:
$ref: '#/components/schemas/Agreement'
documents:
type: array
items:
$ref: '#/components/schemas/ApplicationDocument'
trusted_contact:
$ref: '#/components/schemas/TrustedContact'
account_name:
type: string
account_type:
$ref: '#/components/schemas/AccountType'
custodial_account_type:
type: string
enum:
- UTMA
- UGMA
description: '"UGMA" or "UTMA" only used when account_type is "custodial"'
minor_identity:
$ref: '#/components/schemas/CustodialAccountMinorIdentity'
trading_configurations:
$ref: '#/components/schemas/AccountConfigurations'
required:
- id
- account_number
- status
- currency
- last_equity
- created_at
- account_type
StreetAddress:
type: string
example: 20 N San Mateo Dr
TransferType:
type: string
example: ach
enum:
- ach
- instant_ach
- wire
description: '**NOTE:** The Sandbox environment currently only supports `ach`
- **ach**
Transfer via ACH (US Only).
- **wire**
Transfer via wire (international).
'
title: TransferType
CreateACHRelationshipRequest:
description: 'Represents the fields used in creation of a new ACHRelationship.
You can create an ACHRelationship by passing the required fields here or if you have an account with Plaid you can use our integration with Plaid to create a relationship.
Please see the documentation [here](https://alpaca.markets/docs/api-references/broker-api/funding/ach/#plaid-integration-for-bank-transfers) for more info on using Plaid with Alpaca'
type: object
title: CreateACHRelationshipRequest
properties:
account_owner_name:
type: string
minLength: 1
bank_account_type:
type: string
minLength: 1
enum:
- CHECKING
- SAVINGS
description: Must be CHECKING or SAVINGS
bank_account_number:
type: string
minLength: 1
description: In sandbox, this still must be a valid format
bank_routing_number:
type: string
minLength: 1
description: In sandbox, this still must be a valid format
nickname:
# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/alpaca/refs/heads/main/openapi/alpaca-accounts-api-openapi.yml