Overview

The Option Import Trade API allows you to bulk-create option trades by uploading a spreadsheet containing option contract information. The system validates your data and creates orders in the order management system.

Important: This is a two-step process that requires using both API endpoints in sequence.

How It Works

The process follows these steps:

1. Upload CSV File – Submit your spreadsheet with option trade information
2. System Validates Data – The API checks portfolios, accounts, and data values
3. Review Response – Examine validation results and identify any errors
4. Create Valid Trades – Submit only the valid trades to create actual orders
5. Receive Instance IDs – Get confirmation with instance IDs for tracking

---

---

CSV File Format

What Gets Validate

The upload endpoint performs three levels of validation:

Portfolio Validation

• Checks if portfolios associated with accounts need analytics run
• Verifies portfolio configuration

Account Validation

• Confirms account exists in the system
• Validates account permissions and status

Data Validation

• Verifies all required fields are populated
• Confirms data types and formats are correct
• Checks business rules (example: expiration date must be in the future)
• Validates option quantities are whole numbers
• Ensures actions are valid values (BUY/SELL, OPEN/CLOSE, CALL/PUT)

---

Important: What Is NOT Validated

You are responsible for ensuring accuracy of these values:

• Option Price – The API confirms this is a non-zero decimal but does NOT verify it matches current market prices
• Strike Price – The API confirms this is a non-zero decimal but does NOT verify this strike price exists in the option chain
• Option Contract Existence – The actual option ticker will only be validated during the execution process

The API validates that your data is formatted correctly and follows business rules, but you must ensure the option details are accurate and correspond to real option contracts.

---

Upload Response Scenarios

Scenario 1: Portfolio Requires Analytics

When portfolios need analytics run before trading:

{
  "portfolioFlag": [
    {
      "portfolioId": 55501,
      "needAnalytics": true,
      "failedReason": null
    }
  ],
  "trades": null
}

What this means: You must run analytics on the specified portfolio(s) before you can create trades.

---

Scenario 2: Validation Errors Found

When there are issues with specific trades:

{
  "portfolioFlag": null,
  "trades": [
    {
      "accountId": 456,
      "contractName": null,
      "symbol": "AAPL",
      "tradeAction": 1,
      "last": 84.52,
      "optionType": 0,
      "contractAction": 0,
      "strike": 165.00,
      "expirationDate": "2025-10-06T00:00:00",
      "tradeToolSelection": 6,
      "optionTradeId": 45600001,
      "validateTradeDto": {
        "accountId": 456,
        "accountNumber": "AN123",
        "warningMessage": "The provided Account does not exist.\nCannot purchase expired contract\n",
        "symbol": "AAPL",
        "action": "BUY",
        "isValid": false
      },
      "shareQty": 1000,
      "optionQty": 10
    }
  ]
}

Key Field: validateTradeDto.isValid - When this is false, the trade cannot be created. Check the warningMessage field for details about what failed validation.

---

Scenario 3: All Validations Pass

When all trades pass validation successfully:

{
  "portfolioFlag": null,
  "trades": [
    {
      "accountId": 456,
      "contractName": "@AAPL 251006C00165000",
      "symbol": "AAPL",
      "tradeAction": 1,
      "last": 84.52,
      "optionType": 1,
      "contractAction": 1,
      "strike": 165.0,
      "expirationDate": "2025-10-06T00:00:00",
      "instanceNotes": "",
      "tradeToolSelection": 6,
      "optionTradeId": 31700001,
      "validateTradeDto": {
        "accountId": 456,
        "accountNumber": "HTP.52",
        "securityId": 58,
        "symbol": "AAPL",
        "custodianId": 2,
        "custodian": "Schwab",
        "action": "BUY",
        "orderStatus": "Not sent",
        "warningMessage": "",
        "isEnabled": true,
        "tradeShares": 10.0,
        "isValid": true
      },
      "shareQty": 1000,
      "optionQty": 10
    }
  ]
}

Key Field: validateTradeDto.isValid – When this is true, the trade can be passed to the Save Option Trades endpoint.

---

Understanding the Response Fields

Critical Fields

Field	Location	Description	Importance
isValid	validateTradeDto.isValid	Boolean indicating if trade can be created	CRITICAL – Only trades with true can proceed
warningMessage	validateTradeDto.warningMessage	Description of any validation errors	Explains why validation failed
contractName	Root level	Generated option contract identifier	Required for creating the trade

Additional Response Fields

Field	Description
accountId	Account identifier from CSV file
symbol	Underlying security symbol
tradeAction	Numeric code for trade action (1 = Buy, 2 = Sell)
optionType	Numeric code for option type (1 = Call, 0 = Put)
contractAction	Numeric code for contract action (1 = Open, 0 = Close)
strike	Strike price provided on CSV file
expirationDate	Option expiration date in ISO format
last	‘Option Price’ provided on CSV file
optionQty	Number of contracts
shareQty	Number of shares (contracts × 100)

---

API Endpoint 2: Save Option Trades

Purpose

Creates actual option trade orders in the order management system using validated trade data from the upload endpoint.

Important: Only use this endpoint with trades where isValid is true from the upload response.

Endpoint Information

Method: POST
URL: api/v2/OptionTrading/SaveOptionTrades

Request Requirements

Headers Required:

• Authorization: Bearer YOUR_TOKEN
• Content-Type: application/json

Body Format: JSON array of trade objects

---

Request Body Format

Send an array of trade objects. Each object must contain the following fields:

[
  {
    "accountId": 456,
    "contractAction": 1,
    "contractName": "@AAPL 251006C00165000",
    "currentOptionQty": null,
    "expirationDate": "2025-10-06T00:00:00",
    "instanceNotes": "",
    "last": 84.52,
    "optionQty": 10,
    "optionType": 1,
    "selected": true,
    "strike": 165.0,
    "symbol": "AAPL",
    "tradeAction": 1,
    "tradeToolSelection": 6
  }
]

Request Field Requirements

Field	Type	Required	Description	Source
accountId	Integer	Yes	Account identifier	From upload response
contractAction	Integer	Yes	Contract action code (1=Open, 0=Close)	From upload response
contractName	String	Yes	Option contract identifier	Generated by upload endpoint
currentOptionQty	Integer/Null	No	Current option quantity	Can be null
expirationDate	DateTime	Yes	Option expiration date	From upload response
instanceNotes	String	No	Notes for this trade	Can be empty string
last	Decimal	Yes	Option price	From upload response
optionQty	Integer	Yes	Number of contracts	From upload response
optionType	Integer	Yes	Option type code (1=Call, 0=Put)	From upload response
selected	Boolean	Yes	Selection flag	True
strike	Decimal	Yes	Strike price	From upload response
symbol	String	Yes	Underlying security symbol	From upload response
tradeAction	Integer	Yes	Trade action code (1=Buy, 2=Sell)	From upload response
tradeToolSelection	Integer	Yes	Tool selection code	Always use 6 for import tool

---

Additional Validation Performed

The Save Option Trades endpoint performs deeper validation before creating orders:

Preference Validation

• Checks account preferences and trading restrictions
• Validates against parent security settings

Security Validation

• Ensures underlying security is tradeable for the account
• Verifies account is not overbought or oversold
• Performs same validation as standard equity trades

Order Creation

• Generates trade orders in the order management system
• Returns instance IDs for tracking

---

Save Trades Response

The endpoint returns an integer representing the instance ID of the created trade:

31700001

What this means: Your trade order has been successfully created and assigned this instance ID

If you submit multiple trades in the array, you will receive multiple instance IDs corresponding to each trade in your request.

---

Step-by-Step Workflow

Step 1: Prepare Your CSV File

Create a CSV file with all required columns and your option trade data.

Step 2: Upload File to Validation Endpoint

• Submit your CSV file to api/v2/OptionImport/uploadfile
• Include proper authorization headers

Step 3: Check for Portfolio Flags

• If portfolioFlag is returned with needAnalytics: true, you must run analytics on those portfolios before proceeding
• Cannot create trades until analytics are complete

Step 4: Review Validation Results

• Examine each trade in the trades array
• Review warningMessage for any trades where isValid = false

Step 5: Filter Valid Trades

• Select only trades where isValid = true
• Do NOT attempt to create trades where isValid = false

Step 6: Prepare Save Request

• Extract required fields from valid trades in the upload response
• Use the exact values returned, especially contractName
• Set selected to true and tradeToolSelection to 6

Step 7: Create Trades

• Submit valid trades to api/v2/OptionTrading/SaveOptionTrades
• Include proper authorization and content-type headers

Step 8: Confirm Success

• Receive instance IDs for successfully created trades

---

Common Validation Errors

Error Message	What It Means	How to Fix
“The provided Account does not exist”	Account ID or number is invalid	Verify account exists in the system
“Cannot purchase expired contract”	Expiration date is in the past	Update to a future expiration date
“Portfolio needs analytics”	Portfolio requires analytics run	Run analytics on the portfolio before trading
contractName is null in response	Trade failed validation	Check warningMessage for specific reason

---

Numeric Code Reference

When working with the API responses and requests, you’ll encounter these numeric codes:

Trade Action Codes

• 1 = Buy
• 2 = Sell

Option Type Codes

• 1 = Call
• 0 = Put

Contract Action Codes

• 1 = Open (opening a new position)
• 0 = Close (closing an existing position)

Trade Tool Selection

• 6 = Option Import Tool (always use this value when creating trades from imports)

---

Best Practices

Before You Start

• Ensure all option contract details (prices, strikes, dates) are accurate
• Verify account numbers or IDs are correct
• Confirm expiration dates are in the future

During Implementation

• Always check portfolioFlag before processing trades
• Never attempt to create trades where isValid is false
• Preserve exact field values from the upload response when creating trades

Data Accuracy

Remember: You are responsible for ensuring the accuracy of option prices, strike prices, and contract details. The API validates data format and business rules but does not verify current market prices or that option contracts exist.

---

Important Reminders

• Sequential Process Required – You must call the upload endpoint before the save endpoint
• Contract Name is Generated – The upload endpoint creates the contractName field needed for saving
• Validation Happens Twice – Upload performs initial validation; Save performs deeper trade validation
• Invalid Contracts Caught Late – Non-existent option contracts will only be caught during execution
• One-Way Process – There is no “undo” once trades are created