Clear Street Accounts API

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:
    PortfolioHistorySegment:
      type: object
      required:
      - date
      - realized_pnl
      - unrealized_pnl
      - sod_equity
      - eod_equity
      properties:
        bought_notional:
          type:
          - string
          - 'null'
          description: Amount bought MTM
        date:
          type: string
          format: date
          description: The date for this segment
        day_pnl:
          type:
          - string
          - 'null'
          description: Sum of the profit and loss from intraday trading activities for the trading day.
        eod_equity:
          type: string
          description: The equity at the end of the trading day.
        net_pnl:
          type:
          - string
          - 'null'
          description: P&L after netting all realized and unrealized P&L, adjustments, dividends, change in accruals, income and expenses
        position_pnl:
          type:
          - string
          - 'null'
          description: P&L attributable to start-of-day (carried) positions from market movement during this trading day.
        realized_pnl:
          type: string
          description: Sum of the profit and loss realized from position closing trading activity.
        sod_equity:
          type: string
          description: The equity at the start of the trading day.
        sold_notional:
          type:
          - string
          - 'null'
          description: Amount sold MTM
        unrealized_pnl:
          type: string
          description: Sum of the profit and loss from market changes.
    MarginTopContributor:
      type: object
      required:
      - underlying_instrument_id
      - initial_margin_requirement
      - maintenance_margin_requirement
      - market_value
      - day_trade_buying_power_usage
      properties:
        day_trade_buying_power_usage:
          type: string
          description: 'Day-trade buying power consumed by fills against this underlying on the

            current trade date. Populated only for pattern day trader accounts.'
          deprecated: true
          example: '5000.00'
        initial_margin_requirement:
          type: string
          description: Initial margin requirement attributable to this underlying.
          example: '25000.00'
        maintenance_margin_requirement:
          type: string
          description: Maintenance margin requirement attributable to this underlying.
          example: '15000.00'
        market_value:
          type: string
          description: Net market value attributable to this underlying.
          example: '50000.00'
        underlying_instrument_id:
          type: string
          format: uuid
          description: UUID of the underlying security contributing to margin requirement.
          example: a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8
    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
    MarginSessionDetails:
      type: object
      required:
      - buying_power
      properties:
        buying_power:
          type: string
          description: Maximum buying power available in the account during the session.
          example: '500000.00'
        multiplier:
          type:
          - string
          - 'null'
          description: Effective multiplier for margin calculations during the session.
          example: '2'
      example:
        buying_power: '500000.00'
        multiplier: '2'
    PortfolioHistoryResponse:
      type: object
      required:
      - segments
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/PortfolioHistorySegment'
    ErrorDetails:
      type: array
      items:
        type: object
        additionalProperties: true
    AccountWithPersonalDetails:
      allOf:
      - oneOf:
        - type: object
          description: Represents a trading account
          required:
          - id
          - short_name
          - full_name
       

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