Sign in

v57

latestOpenAPI 3.1.0Proprietaryraw.githubusercontent.com2026-07-2161198428.4 KB
Positions

Submit Position Instructions

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 instruction_id; the top-level error summarizes the batch.
post/v1/accounts/{account_id}/positions/instructions

Path parameters

account_idinteger required

Account identifier

Request body

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

[
  {
    "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"
  },
  "data": [
    {
      "accepted_quantity": null,
      "account_id": 122503,
      "created_at": "2026-04-24T14:30:00Z",
      "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02",
      "instruction_id": "ui-20260424-001",
      "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"
    }
  ]
}