PositionInstruction

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/clearstreet8e71/main/json-schema/clearstreet8e71-position-instruction-schema.json",
  "title": "PositionInstruction",
  "description": "A position instruction and its current lifecycle state.",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/clearstreet8e71-openapi.yaml#/components/schemas/PositionInstruction",
  "type": "object",
  "required": [
    "id",
    "client_instruction_id",
    "account_id",
    "instruction_type",
    "instrument_id",
    "symbol",
    "quantity",
    "status"
  ],
  "properties": {
    "accepted_quantity": {
      "type": [
        "string",
        "null"
      ],
      "description": "Number of contracts accepted by the clearing venue. Populated once\nthe instruction reaches `ACCEPTED`.\nWhen a null/undefined value is observed, it indicates that there is no available data."
    },
    "account_id": {
      "$ref": "#/$defs/i64",
      "description": "Account the instruction belongs to."
    },
    "client_instruction_id": {
      "type": "string",
      "description": "Caller-supplied idempotency key echoed from the submit request; the\nserver-assigned fallback when none was supplied."
    },
    "created_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the instruction was first accepted by the service.\nWhen a null/undefined value is observed, it indicates that there is no available data."
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Server-assigned id. Used as the path parameter on cancel."
    },
    "instruction_type": {
      "$ref": "#/$defs/PositionInstructionType",
      "description": "The action this instruction requests."
    },
    "instrument_id": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier of the options contract this instruction acts on."
    },
    "quantity": {
      "type": "string",
      "description": "Number of contracts included in the instruction."
    },
    "rejection": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/PositionInstructionRejection",
          "description": "Machine-readable counterpart to `rejection_reason`: a stable reason code,\nhuman-readable `description`, and params, present on every rejected row —\non submit, cancel, get, and list alike. Branch on `rejection.reason` and\nread `rejection.description` instead of the top-level `rejection_reason`.\nWhen a null/undefined value is observed, it indicates it does not apply."
        }
      ]
    },
    "rejection_reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Human-readable explanation populated on any non-success terminal\nstatus — `REJECTED` or `CANCEL_FAILED`. On a\n`207 Multi-Status` batch submit the top-level `error` field\nsummarizes the batch; per-row detail continues to live here.\nWhen a null/undefined value is observed, it indicates it does not apply."
    },
    "status": {
      "$ref": "#/$defs/PositionInstructionStatus",
      "description": "Current lifecycle status."
    },
    "symbol": {
      "type": "string",
      "description": "Options symbol (OSI) for display."
    },
    "underlying_instrument_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Identifier of the underlying instrument, when available.\nWhen a null/undefined value is observed, it indicates it does not apply."
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the instruction's lifecycle state last changed.\nWhen a null/undefined value is observed, it indicates that there is no available data."
    }
  },
  "$defs": {
    "PositionInstructionRejection": {
      "type": "object",
      "description": "Machine-readable detail for a rejected position instruction.\n\nPresent on every rejected row, across the full lifecycle — submit, cancel,\nget, and list. Branch on `reason` for programmatic handling and template your\nown copy from `metadata`, or show `description` directly.",
      "required": [
        "domain",
        "reason",
        "description",
        "metadata"
      ],
      "properties": {
        "description": {
          "type": "string",
          "description": "Human-readable explanation of the rejection. Duplicates the top-level\n`rejection_reason`; prefer this field."
        },
        "domain": {
          "type": "string",
          "description": "Namespacing domain of the `reason` code — `com.clearstreet.oems.exercise`\nfor reasons OEMS validates, `com.clearstreet.oems.clearing` for\nclearing-owned reasons."
        },
        "metadata": {
          "type": "object",
          "description": "Reason-specific parameters as a string→string map. Which keys are present\ndepends on `reason`:\n\n- `INSUFFICIENT_POSITION` → `available`, `requested`\n- `DNE_NOT_ON_EXPIRY` / `CEA_NOT_ON_EXPIRY` → `expiry`, `business_date`\n- `EXERCISE_PAST_CUTOFF` → `cutoff_time`\n- `DUPLICATE_INSTRUCTION` → `existing_id`\n\nEmpty for reasons that carry no parameters. New keys may be added over\ntime, so treat unknown keys leniently.",
          "additionalProperties": {
            "type": "string"
          },
          "propertyNames": {
            "type": "string"
          }
        },
        "reason": {
          "type": "string",
          "description": "Stable, machine-readable reason code, e.g. `DNE_NOT_ON_EXPIRY`,\n`INSUFFICIENT_POSITION`, `OPTIONS_LEVEL_EXCEEDED`, `EXERCISE_PAST_CUTOFF`."
        }
      }
    },
    "PositionInstructionStatus": {
      "type": "string",
      "description": "Lifecycle status of a position instruction.\n\n- `SENT`: accepted and submitted to the clearing venue.\n- `ACCEPTED`: terminal — accepted by the clearing venue.\n- `REJECTED`: terminal rejection; `rejection_reason` carries the\n  detail. Covers both venue-reported rejections and rejections\n  raised before the instruction reached the clearing venue (e.g.\n  duplicate `client_instruction_id`, `DO_NOT_EXERCISE` / `CONTRARY_EXERCISE`\n  submitted on a non-expiry day, insufficient position, or an\n  instrument that does not resolve).\n- `CANCEL_REQUESTED`: cancel accepted; final cancel state pending.\n- `CANCELLED`: terminal — cancel completed.\n- `CANCEL_FAILED`: cancel could not be completed; operator\n  attention required. `rejection_reason` carries the detail.\n- `UNKNOWN`: status could not be determined.",
      "enum": [
        "SENT",
        "ACCEPTED",
        "REJECTED",
        "CANCEL_REQUESTED",
        "CANCELLED",
        "CANCEL_FAILED",
        "UNKNOWN"
      ]
    },
    "PositionInstructionType": {
      "type": "string",
      "description": "The action to take against an options position.",
      "enum": [
        "EXERCISE",
        "DO_NOT_EXERCISE",
        "CONTRARY_EXERCISE"
      ]
    },
    "i64": {
      "type": "integer",
      "format": "int64"
    }
  }
}