Positions

Submit Position Instructions

Changed on Oct 16, 2026

Submit one or more position instructions (Exercise, Do-Not-Exercise, Contrary Exercise Advice) against the account.

Batch semantics:

All rows accepted → 200 OK. Every row is in data with status = SENT.
Partial success → 207 Multi-Status. data contains every row; rejected rows carry status = REJECTED and rejection_reason. The top-level error summarizes the batch failure.
All rows rejected → 4xx/5xx. The HTTP status reflects the aggregate cause: 409 when every row was a duplicate, 400 for validation failures like DNE/CEA on a non-expiry day, 503 if the clearing service is unavailable. data still contains every row carrying status = REJECTED and rejection_reason so callers can attribute failures by client_instruction_id; the top-level error summarizes the batch.

post/v1/accounts/{account_id}/positions/instructions

Request

Base URL
https://api.clearstreet.com
Auth
HTTP bearer

Path parameters

account_idinteger required

Account identifier

Request body

client_instruction_idstring nullable

Caller-supplied idempotency key. Echoed on the response. The server generates a unique id when omitted.

instruction_type'EXERCISE' | 'DO_NOT_EXERCISE' | 'CONTRARY_EXERCISE' required

The action to take against an options position.

instrument_idstring uuid required

Identifier of the options contract to act on. Unknown ids return 404.

quantitystring required

Number of contracts to include in the instruction.

Example request

[
  {
    "client_instruction_id": "ui-20260424-001",
    "instruction_type": "EXERCISE",
    "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02",
    "quantity": "1"
  }
]

Response

All instructions accepted

Example response

{
  "error": {
    "code": 400,
    "message": "Order quantity must be greater than zero"
  },
  "metadata": {
    "page_number": 1,
    "total_items": 42,
    "total_pages": 5
  },
  "data": [
    {
      "accepted_quantity": null,
      "account_id": 122503,
      "client_instruction_id": "ui-20260424-001",
      "created_at": "2026-04-24T14:30:00Z",
      "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02",
      "instruction_type": "EXERCISE",
      "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02",
      "quantity": "1",
      "rejection_reason": null,
      "status": "SENT",
      "symbol": "AAPL  280121C00195000",
      "updated_at": "2026-04-24T14:30:00Z"
    }
  ]
}

Changes

Oct 16, 20261bd9eddeffc8 Revision changes
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- warning
  removed the request property /
- info
  added the new optional request property /
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
Jun 10, 202699644beba9d7 Revision changes
- info
  removed the ENGINE_REJECTED enum value from the /// response property for the response status
- info
  removed the ENGINE_REJECTED enum value from the /// response property for the response status
- info
  removed the ENGINE_REJECTED enum value from the /// response property for the response status
- info
  removed the ENGINE_REJECTED enum value from the /// response property for the response status
- info
  removed the ENGINE_REJECTED enum value from the /// response property for the response status
- info
  removed the ENGINE_REJECTED enum value from the /// response property for the response status

Operation history (4 revisions)