The Accounts API from Clear Street — 6 operation(s) for accounts.
openapi: 3.2.0
info:
title: Clear Street Accounts API
version: '1.0'
description: 'Operations tagged Accounts across 2 of this provider''s published API definitions: clear-street-studio-openapi.yml, clear-street-trading-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.clearstreet.io/studio/v2
description: Production environment
- url: https://sandbox-api.clearstreet.io/studio/v2
description: Sandbox environment
- url: https://api.clearstreet.com
description: Clear Street API
- url: https://api-dev.clearstreet.com
description: Clear Street Development API
- url: http://localhost:5001
description: Clear Street Local API
tags:
- name: Accounts
x-displayName: Accounts
paths:
/accounts:
servers:
- url: https://api.clearstreet.io/studio/v2
description: Production environment
- url: https://sandbox-api.clearstreet.io/studio/v2
description: Sandbox environment
get:
operationId: listAccounts
summary: List accounts
description: List all available accounts.
tags:
- Accounts
responses:
'200':
description: A list of accounts
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Account'
default:
$ref: '#/components/responses/error'
security:
- BearerAuth: []
/accounts/{account_id}:
servers:
- url: https://api.clearstreet.io/studio/v2
description: Production environment
- url: https://sandbox-api.clearstreet.io/studio/v2
description: Sandbox environment
get:
operationId: getAccount
summary: Get account
description: Get an account by its ID or number.
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: The ID or number of the account to get.
schema:
$ref: '#/components/schemas/AccountId'
responses:
'200':
description: The account
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
default:
$ref: '#/components/responses/error'
security:
- BearerAuth: []
/v1/accounts:
servers:
- url: https://api.clearstreet.com
description: Clear Street API
- url: https://api-dev.clearstreet.com
description: Clear Street Development API
- url: http://localhost:5001
description: Clear Street Local API
get:
tags:
- Accounts
summary: Get Accounts
description: 'List accounts the authenticated user has permission to access.
Results can be narrowed with the optional `account_id` and `account_name`
filters. `account_id` is a lexicographic prefix match on the decimal account
id (e.g. `100` matches `100345` and `100567`); `account_name` is a
case-insensitive substring match on the account''s full name. When both are
supplied an account must match both. When neither is supplied every
accessible account is returned.'
operationId: get_accounts
parameters:
- name: page_size
in: query
description: The number of items to return per page. Only used when page_token is not provided.
required: false
schema:
type: integer
format: int64
default: 1000
maximum: 1000
minimum: 1
- name: page_token
in: query
description: Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored.
required: false
schema:
type: string
format: byte
description: Base64URL-encoded pagination token
example: eyJvZmZzZXQiOjEwMCwibGltaXQiOjEwMH0=
- name: account_id
in: query
description: Filter to accounts whose id starts with this value (lexicographic prefix match on the decimal id, e.g. `100` matches `100345`).
required: false
schema:
type: string
- name: account_name
in: query
description: Filter to accounts whose full name contains this value (case-insensitive substring match).
required: false
schema:
type: string
responses:
'200':
description: List of accounts
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/AccountList'
type: object
examples:
ActiveAndInactiveAccounts:
summary: A mix of active and closed accounts
value:
data:
- account_holder_entity_id: 987654321
close_date: null
full_name: Test Trading Account
id: 19816
open_date: 2023-01-15
options_level: 1
short_name: TST-ACCOUNT-01
status: ACTIVE
subtype: MARGIN
type: CUSTOMER
- account_holder_entity_id: 987654322
close_date: 2024-08-01
full_name: Old Test Account
id: 19817
open_date: 2021-05-20
options_level: 0
short_name: TST-ACCOUNT-02-CLOSED
status: CLOSED
subtype: CASH
type: CUSTOMER
error: null
metadata:
next_page_token: cGFnZT0yJmxhc3RfaWQ9MTk4MTc=
page_number: 1
request_id: a1b2c3d4-e5f6-7890-1234-567890abcdef
total_items: 25
total_pages: 3
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
Forbidden:
summary: Caller does not have permission
value:
error:
code: 403
message: The caller does not have permission to execute the specified operation
metadata:
request_id: 5518f0c6-58ff-4b4a-81a5-701556d41206
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- BearerAuth: []
/v1/accounts/{account_id}:
servers:
- url: https://api.clearstreet.com
description: Clear Street API
- url: https://api-dev.clearstreet.com
description: Clear Street Development API
- url: http://localhost:5001
description: Clear Street Local API
get:
tags:
- Accounts
summary: Get Account By ID
description: 'Fetch account details by ID, including the mailing address, date of
birth, phone number, and country of tax residency of the account-holder
entity when on file.'
operationId: get_account_by_id
parameters:
- name: account_id
in: path
description: Account identifier
required: true
schema:
$ref: '#/components/schemas/i64'
responses:
'200':
description: Account details
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/AccountWithPersonalDetails'
type: object
examples:
ActiveAccount:
summary: An active margin account
value:
data:
account_holder_entity_id: 987654321
close_date: null
country_of_tax_residency: US
date_of_birth: 1985-03-15
full_name: Test Trading Account
id: 19816
mailing_address:
city: New York
country: USA
line1: 4 World Trade Center
line2: 150 Greenwich Street, Floor 45
postal_code: '10007'
state: NY
open_date: 2023-01-15
options_level: 1
phone_number: '+12125550123'
short_name: TST-ACCOUNT-01
status: ACTIVE
subtype: MARGIN
type: CUSTOMER
error: null
metadata:
request_id: b7e2d3f4-a1b2-4c3d-8e4f-5a6b7c8d9e0f
ClosedAccount:
summary: A closed cash account with no entity details on file
value:
data:
account_holder_entity_id: 987654322
close_date: 2024-08-01
country_of_tax_residency: null
date_of_birth: null
full_name: Old Test Account
id: 19817
mailing_address: null
open_date: 2021-05-20
options_level: 0
phone_number: null
short_name: TST-ACCOUNT-02-CLOSED
status: CLOSED
subtype: CASH
type: CUSTOMER
error: null
metadata:
request_id: c8f3e4a5-b2c3-5d4e-9f0a-6b7c8d9e0f1a
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
Forbidden:
summary: Caller does not have permission
value:
error:
code: 403
message: The caller does not have permission to execute the specified operation
metadata:
request_id: 5518f0c6-58ff-4b4a-81a5-701556d41206
'404':
description: Account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
AccountNotFound:
summary: Requested account does not exist
value:
error:
code: 404
message: Some requested entity was not found
metadata:
request_id: 67e95eb4-93b9-4010-8c9b-7ada7c2be93f
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- BearerAuth: []
patch:
tags:
- Accounts
summary: Patch Account By ID
description: Update account risk settings
operationId: patch_account_by_id
parameters:
- name: account_id
in: path
description: Account identifier
required: true
schema:
$ref: '#/components/schemas/i64'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAccountSettingsRequest'
required: true
responses:
'200':
description: Account updated successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/AccountSettings'
type: object
examples:
UpdatedAccountSettings:
summary: Account with updated settings applied
value:
data:
risk:
max_notional: '5000000.00'
error: null
metadata:
request_id: c8f3e4a5-b2c3-5d4e-9f0a-6b7c8d9e0f1a
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
MalformedJsonSyntax:
summary: Malformed JSON in request body
value:
error:
code: 400
message: 'Failed to parse the request body as JSON: EOF while parsing an object at line 5 column 3'
metadata:
request_id: 5805829b-238e-4669-846b-d768bc5d279c
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
Forbidden:
summary: Caller does not have permission
value:
error:
code: 403
message: The caller does not have permission to execute the specified operation
metadata:
request_id: 5518f0c6-58ff-4b4a-81a5-701556d41206
'404':
description: Account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
AccountNotFound:
summary: Requested account does not exist
value:
error:
code: 404
message: Some requested entity was not found
metadata:
request_id: 67e95eb4-93b9-4010-8c9b-7ada7c2be93f
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- BearerAuth: []
/v1/accounts/{account_id}/balances:
servers:
- url: https://api.clearstreet.com
description: Clear Street API
- url: https://api-dev.clearstreet.com
description: Clear Street Development API
- url: http://localhost:5001
description: Clear Street Local API
get:
tags:
- Accounts
summary: Get Account Balances
description: Fetch account balance information
operationId: get_account_balances
parameters:
- name: account_id
in: path
description: Account identifier
required: true
schema:
$ref: '#/components/schemas/i64'
- name: top_margin_contributors_limit
in: query
description: Limit the number of top margin contributors returned.
required: false
schema:
type: integer
format: int32
minimum: 1
example: 10
responses:
'200':
description: Account balance information
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/AccountBalances'
type: object
examples:
CashAccountBalances:
summary: Balances for a cash account
value:
data:
account_id: 19816
buying_power: '45000.00'
currency: USD
daily_change: '0.00'
daily_pnl: '1250.00'
daily_realized_pnl: '700.00'
daily_total_pnl: '1250.00'
daily_unrealized_pnl: '550.00'
equity: '100000.00'
long_market_value: '30000.00'
margin_type: NONE
open_order_adjustment: '-5000.00'
settled_cash: '60000.00'
sod:
asof: 2023-09-27
buying_power: '45000.00'
equity: '100000.00'
long_market_value: '30000.00'
short_market_value: '0.00'
trade_cash: '60000.00'
unrealized_pnl: '1500.00'
unsettled_credits: '20000.00'
unsettled_debits: '10000.00'
withdrawable_cash: '55000.00'
error: null
metadata:
request_id: b7e2d3f4-a1b2-4c3d-8e4f-5a6b7c8d9e0f
MarginAccountBalances:
summary: Balances for a Reg T margin account
value:
data:
account_id: 19816
buying_power: '90000.00'
currency: USD
daily_change: '0.00'
daily_pnl: '1250.00'
daily_realized_pnl: '700.00'
daily_total_pnl: '1250.00'
daily_unrealized_pnl: '550.00'
equity: '100000.00'
long_market_value: '40000.00'
margin_details:
day_trade_buying_power_usage: '0.00'
day_trade_count: 2
initial_margin_excess: '50000.00'
initial_margin_requirement: '50000.00'
intraday_details:
buying_power: '90000.00'
multiplier: '2'
maintenance_margin_excess: '75000.00'
maintenance_margin_requirement: '25000.00'
overnight_details:
buying_power: '90000.00'
multiplier: '2'
pattern_day_trader: false
top_contributors:
- initial_margin_requirement: '25000.00'
maintenance_margin_requirement: '15000.00'
market_value: '50000.00'
underlying_instrument_id: a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8
usage:
total: '100000.00'
used: '5000.00'
margin_type: REG_T
multiplier: '2'
open_order_adjustment: '-10000.00'
settled_cash: '99775.05'
short_market_value: '10000.00'
sod:
asof: 2023-09-27
buying_power: '90000.00'
day_trade_buying_power: '200000.00'
equity: '100000.00'
long_market_value: '40000.00'
maintenance_margin_excess: '50000.00'
maintenance_margin_requirement: '50000.00'
short_market_value: '10000.00'
trade_cash: '70000.00'
trade_cash: '70000.00'
unrealized_pnl: '1500.00'
unsettled_credits: '20000.00'
unsettled_debits: '10000.00'
withdrawable_cash: '75000.00'
error: null
metadata:
request_id: b7e2d3f4-a1b2-4c3d-8e4f-5a6b7c8d9e0f
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
Forbidden:
summary: Caller does not have permission
value:
error:
code: 403
message: The caller does not have permission to execute the specified operation
metadata:
request_id: 5518f0c6-58ff-4b4a-81a5-701556d41206
'404':
description: Account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
AccountNotFound:
summary: Requested account does not exist
value:
error:
code: 404
message: Some requested entity was not found
metadata:
request_id: 67e95eb4-93b9-4010-8c9b-7ada7c2be93f
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- BearerAuth: []
/v1/accounts/{account_id}/portfolio-history:
servers:
- url: https://api.clearstreet.com
description: Clear Street API
- url: https://api-dev.clearstreet.com
description: Clear Street Development API
- url: http://localhost:5001
description: Clear Street Local API
get:
tags:
- Accounts
summary: Get Portfolio History
description: Retrieves daily portfolio history for the specified account.
operationId: get_portfolio_history
parameters:
- name: account_id
in: path
description: Account identifier
required: true
schema:
type: integer
format: int64
- name: start_date
in: query
description: Start date for the portfolio history range, in YYYY-MM-DD format.
required: true
schema:
type: string
format: date
- name: end_date
in: query
description: Defaults to today in America/New_York when omitted.
required: false
schema:
type: string
format: date
responses:
'200':
description: Portfolio history
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/PortfolioHistoryResponse'
type: object
examples:
PortfolioHistoryWithItems:
summary: Portfolio history with segments
value:
data:
segments:
- bought_notional: '39800.00'
date: 2026-04-15
day_pnl: '850.25'
eod_equity: '100850.25'
net_pnl: '850.25'
position_pnl: '-350.25'
realized_pnl: '1200.50'
sod_equity: '100000.00'
sold_notional: '42500.00'
unrealized_pnl: '-350.25'
error: null
metadata:
request_id: f076d6f6-10c9-42a0-98c5-18cebc427e80
'207':
description: 'Partial success: some data is available but the full request could not be completed'
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/PortfolioHistoryResponse'
type: object
examples:
HistoryFailedIntradayOk:
summary: Historical fetch failed but intraday segment is available
value:
data:
segments:
- bought_notional: null
date: 2026-05-12
day_pnl: null
eod_equity: '100009.00'
net_pnl: null
position_pnl: null
realized_pnl: '12.00'
sod_equity: '100000.00'
sold_notional: null
unrealized_pnl: '-3.00'
error:
code: 500
message: historical data temporarily unavailable
metadata:
request_id: 2f3d7b0a-1111-4a4b-9e1f-8c4e5d3a9f12
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
Forbidden:
summary: Caller does not have permission
value:
error:
code: 403
message: The caller does not have permission to execute the specified operation
metadata:
request_id: 5518f0c6-58ff-4b4a-81a5-701556d41206
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- BearerAuth: []
components:
schemas:
ResponseMetadata:
type: object
description: 'Metadata for the response. This will always contain a request ID which can be used to identify
the request to Clear Street for tracing, and optionally may include pagination data.'
required:
- request_id
properties:
next_page_token:
oneOf:
- type: 'null'
- type: string
format: byte
description: Base64URL-encoded pagination token
description: 'A token that can be used to retrieve the next page of results, if any.
The token contains opaque pagination state.
Filtering and sorting parameters must be provided with each request.'
page_number:
type:
- integer
- 'null'
format: int32
description: Pagination. Included if this was a GET (list) response
example: '1'
minimum: 0
previous_page_token:
oneOf:
- type: 'null'
- type: string
format: byte
description: Base64URL-encoded pagination token
description: 'A token that can be used to retrieve the previous page of results, if any.
The token contains opaque pagination state.
Filtering and sorting parameters must be provided with each request.'
request_id:
type: string
description: A unique ID for this request, generated upon ingestion of the request.
total_items:
type:
- integer
- 'null'
format: int64
description: Total number of items available (not just in this page).
example: '42'
minimum: 0
total_pages:
type:
- integer
- 'null'
format: int32
description: Total number of pages available.
example: '5'
minimum: 0
Account_2:
type: object
description: Represents a trading account
required:
- id
- short_name
- full_name
- type
- subtype
- open_date
- account_holder_entity_id
- options_level
- status
properties:
account_holder_entity_id:
type: integer
format: int64
description: The account holder entity identifier
example: 987654321
close_date:
type:
- string
- 'null'
format: date
description: 'The date the account was closed, if applicable
When a null/undefined value is observed, it indicates it does not apply.'
example: 2026-01-15
full_name:
type: string
description: The full legal name of the account
example: Test Trading Account
id:
$ref: '#/components/schemas/i64'
description: The unique identifier for the account
open_date:
type: string
format: date
description: The date the account was opened
example: 2023-01-15
options_level:
$ref: '#/components/schemas/i64'
description: The options level of the account
short_name:
type: string
description: The short name of the account
example: TST-ACCOUNT-01
status:
$ref: '#/components/schemas/AccountStatus'
description: The current status of the account
subtype:
$ref: '#/components/schemas/AccountSubtype'
description: The sub-type of account
type:
$ref: '#/components/schemas/AccountType'
description: The type of account
example:
account_holder_entity_id: 987654321
close_date: null
full_name: Test Trading Account
id: 19816
open_date: 2023-01-15
options_level: 1
short_name: TST-ACCOUNT-01
status: ACTIVE
subtype: MARGIN
type: CUSTOMER
Account:
type: object
properties:
account_id:
$ref: '#/components/schemas/AccountId'
account_number:
$ref: '#/components/schemas/AccountNumber'
entity_id:
$ref: '#/components/schemas/EntityId'
name:
type: string
example: Clear Street
required:
- account_id
- account_number
- entity_id
- name
AccountSubtype:
type: string
description: Account subtype classification providing more granular categorization
enum:
- CASH
- MARGIN
- OTHER
RiskSettings:
type: object
description: Risk settings for an account
properties:
max_notional:
type:
- string
- 'null'
description: 'The maximum notional value available to the account
When a null/undefined value is observed, it indicates that there is no available data.'
example: '1000000.00'
MarginType:
type: string
description: An account's margin type
enum:
- OTHER
- NONE
- PORTFOLIO_MARGIN
- RISK_BASED_HAIRCUT_BROKER_DEALER
- REG_T
- RISK_BASED_HAIRCUT_MARKET_MAKER
- CIRO
- FUTURES_NLV
- FUTURES_TOT_EQ
AccountBalancesSod:
type: object
required:
- buying_power
- equity
- long_market_value
- short_market_value
properties:
asof:
type:
- string
- 'null'
format: date
description: 'Timestamp for the start-of-day values.
When a null/undefined value is observed, it indicates that there is no available data.'
example: 2023-09-27
buying_power:
type: string
description: Start-of-day buying power.
example: '90000.00'
day_trade_buying_power:
type:
- string
- 'null'
description: 'Start-of-day day-trade buying p
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clear-street/refs/heads/main/openapi/clear-street-accounts-api-openapi.yml