Skip to content
Clear Street Clear Street
Get started
API Reference
V1
Positions

Submit Position Instructions

client.V1.Positions.SubmitPositionInstructions(ctx, accountID, body) (*V1PositionSubmitPositionInstructionsResponse, error)
POST/v1/accounts/{account_id}/positions/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 = ENGINE_REJECTED (or REJECTED) and rejection_reason. The top-level error summarizes the batch failure.
  • All rows rejected → 4xx/5xx error response. The HTTP status reflects the underlying cause: 409 for duplicate instruction_id, 400 for validation failures such as DNE/CEA on a non-expiry day, 503 if the clearing service is unavailable. No data is returned.

Pre-flight validation (unknown instrument_id, unencodable quantity) short-circuits the whole batch with a 4xx before any row is submitted.

ParametersExpand Collapse
accountID int64
body V1PositionSubmitPositionInstructionsParams
Instructions param.Field[[]V1PositionSubmitPositionInstructionsParamsInstruction]
InstructionType PositionInstructionType

The action to take.

One of the following:
const PositionInstructionTypeExercise PositionInstructionType = "EXERCISE"
const PositionInstructionTypeDoNotExercise PositionInstructionType = "DO_NOT_EXERCISE"
const PositionInstructionTypeContraryExercise PositionInstructionType = "CONTRARY_EXERCISE"
InstrumentID string

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

formatuuid
Quantity string

Number of contracts to include in the instruction.

InstructionID stringOptional

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

ReturnsExpand Collapse
type V1PositionSubmitPositionInstructionsResponse struct{…}
ID string

Server-assigned id. Used as the path parameter on cancel.

formatuuid
AccountID int64

Account the instruction belongs to.

formatint64
InstructionID string

Caller-supplied idempotency key echoed from the submit request; the server-assigned fallback when none was supplied.

InstructionType PositionInstructionType

The action this instruction requests.

One of the following:
const PositionInstructionTypeExercise PositionInstructionType = "EXERCISE"
const PositionInstructionTypeDoNotExercise PositionInstructionType = "DO_NOT_EXERCISE"
const PositionInstructionTypeContraryExercise PositionInstructionType = "CONTRARY_EXERCISE"
InstrumentID string

Identifier of the options contract this instruction acts on.

formatuuid
Quantity string

Number of contracts included in the instruction.

Current lifecycle status.

One of the following:
const PositionInstructionStatusSent PositionInstructionStatus = "SENT"
const PositionInstructionStatusAccepted PositionInstructionStatus = "ACCEPTED"
const PositionInstructionStatusRejected PositionInstructionStatus = "REJECTED"
const PositionInstructionStatusEngineRejected PositionInstructionStatus = "ENGINE_REJECTED"
const PositionInstructionStatusCancelRequested PositionInstructionStatus = "CANCEL_REQUESTED"
const PositionInstructionStatusCancelled PositionInstructionStatus = "CANCELLED"
const PositionInstructionStatusCancelFailed PositionInstructionStatus = "CANCEL_FAILED"
const PositionInstructionStatusUnknown PositionInstructionStatus = "UNKNOWN"
Symbol string

Options symbol (OSI) for display.

AcceptedQuantity stringOptional

Number of contracts accepted by the clearing venue. Populated once the instruction reaches ACCEPTED.

CreatedAt TimeOptional

When the instruction was first accepted by the service.

formatdate-time
RejectionReason stringOptional

Human-readable explanation populated on any non-success terminal status — REJECTED, ENGINE_REJECTED, or CANCEL_FAILED. On a 207 Multi-Status batch submit the top-level error field summarizes the batch; per-row detail continues to live here.

UpdatedAt TimeOptional

When the instruction’s lifecycle state last changed.

formatdate-time

Submit Position Instructions

package main

import (
  "context"
  "fmt"

  "github.com/clear-street/clear-street-go"
  "github.com/clear-street/clear-street-go/option"
)

func main() {
  client := clearstreet.NewClient(
    option.WithAPIKey("My API Key"),
  )
  response, err := client.V1.Positions.SubmitPositionInstructions(
    context.TODO(),
    0,
    clearstreet.V1PositionSubmitPositionInstructionsParams{
      Instructions: []clearstreet.V1PositionSubmitPositionInstructionsParamsInstruction{clearstreet.V1PositionSubmitPositionInstructionsParamsInstruction{
        InstructionType: clearstreet.PositionInstructionTypeExercise,
        InstrumentID: "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02",
        Quantity: "1",
      }},
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response)
}

{
  "data": [
    {
      "account_id": 122503,
      "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02",
      "instruction_id": "ui-20260424-001",
      "instruction_type": "EXERCISE",
      "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01",
      "quantity": "1",
      "status": "SENT",
      "symbol": "AAPL  280121C00195000"
    }
  ],
  "metadata": {
    "request_id": "0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd01"
  }
}
{
  "data": [
    {
      "account_id": 122503,
      "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02",
      "instruction_id": "ui-20260424-001",
      "instruction_type": "EXERCISE",
      "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01",
      "quantity": "1",
      "status": "SENT",
      "symbol": "AAPL  280121C00195000"
    },
    {
      "account_id": 122503,
      "id": "00000000-0000-0000-0000-000000000000",
      "instruction_id": "ui-20260424-001",
      "instruction_type": "EXERCISE",
      "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01",
      "quantity": "1",
      "rejection_reason": "Duplicate exercise instruction",
      "status": "ENGINE_REJECTED",
      "symbol": "AAPL  280121C00195000"
    }
  ],
  "error": {
    "code": 409,
    "message": "Duplicate exercise instruction"
  },
  "metadata": {
    "request_id": "0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd02"
  }
}
{
  "error": {
    "code": 400,
    "message": "DO_NOT_EXERCISE must be submitted on the contract's expiration date"
  },
  "metadata": {
    "request_id": "0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd03"
  }
}
{
  "error": {
    "code": 409,
    "message": "Duplicate exercise instruction"
  },
  "metadata": {
    "request_id": "0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd04"
  }
}
Returns Examples
{
  "data": [
    {
      "account_id": 122503,
      "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02",
      "instruction_id": "ui-20260424-001",
      "instruction_type": "EXERCISE",
      "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01",
      "quantity": "1",
      "status": "SENT",
      "symbol": "AAPL  280121C00195000"
    }
  ],
  "metadata": {
    "request_id": "0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd01"
  }
}
{
  "data": [
    {
      "account_id": 122503,
      "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02",
      "instruction_id": "ui-20260424-001",
      "instruction_type": "EXERCISE",
      "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01",
      "quantity": "1",
      "status": "SENT",
      "symbol": "AAPL  280121C00195000"
    },
    {
      "account_id": 122503,
      "id": "00000000-0000-0000-0000-000000000000",
      "instruction_id": "ui-20260424-001",
      "instruction_type": "EXERCISE",
      "instrument_id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01",
      "quantity": "1",
      "rejection_reason": "Duplicate exercise instruction",
      "status": "ENGINE_REJECTED",
      "symbol": "AAPL  280121C00195000"
    }
  ],
  "error": {
    "code": 409,
    "message": "Duplicate exercise instruction"
  },
  "metadata": {
    "request_id": "0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd02"
  }
}
{
  "error": {
    "code": 400,
    "message": "DO_NOT_EXERCISE must be submitted on the contract's expiration date"
  },
  "metadata": {
    "request_id": "0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd03"
  }
}
{
  "error": {
    "code": 409,
    "message": "Duplicate exercise instruction"
  },
  "metadata": {
    "request_id": "0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd04"
  }
}