Trades Endpoint

Complete documentation for the VOTR Trades API endpoint

📚 Interactive API Documentation

For a complete interactive API documentation with live testing capabilities, visit our Swagger documentation:

🔗 Trades API Swagger Documentation - Try It Now!

The Swagger documentation provides:

  • Interactive API endpoint testing
  • Detailed request/response schemas
  • Authentication examples
  • Real-time API exploration
  • Code generation for multiple languages

You can also download the OpenAPI specification: trades-api-spec.yaml

Trades Data Submission

The Trades endpoint allows brokers to bulk-enqueue daily trade data that combines trade-side and shareholder-side information into a single record per item. Records are queued for asynchronous processing. Duplicate suppression is performed downstream on the compound key cusip | tradeDate | shareholderAccountNo.

API Endpoints

Development:

POST https://shareholders-api-dev.govotr.com/api/v1/trade

Production:

POST https://shareholders-api.govotr.com/api/v1/trade

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Note: This endpoint uses the same OAuth 2.0 Bearer token authentication as other VOTR API calls. Obtain your access token from the OAuth Token endpoint before making requests.

Request Schema

Main Request Object

Field Type Required Description
tradeDataList array ✅ Array of merged trade + shareholder records (1–50 items per request)

Data Item Schema

Each item in the tradeDataList array must contain the following fields:

Required Fields

Field Type Description
cusip string CUSIP identifier for the security
issuer string Name of the issuing company
tradeDate string Date when the trade occurred (ISO 8601 in UTC, e.g. "2024-01-15T00:00:00Z")
shareholderAccountNo string Account number of the shareholder
brokerTxnId string Broker-side transaction identifier
ticker string Ticker symbol for the security
tradeQty number Quantity of shares traded (must be ≥ 0)
tradeAction string Trade action performed. One of "BUY" or "SELL"
securityType string Top-level security classification (see Security Type → Sub-Type Mapping below)
securitySubType string Security sub-type. Must be valid for the chosen securityType
shareholderName string Name of the shareholder
deliveryPreference string Preferred delivery method. One of "E-Delivery" or "Full Set"
settlementDate string Settlement date for the trade (ISO 8601 in UTC, e.g. "2024-01-17T00:00:00Z")
brokerId string ObjectId of the associated clearing broker

Important:

  • When deliveryPreference = "E-Delivery", shareholderEmail is required and must be a valid email address.
  • When deliveryPreference = "Full Set", shareholderPhysicalAddress is required, and the addressLine1, city, state, zipCode, and country fields within it must be provided.
  • securitySubType must be a valid sub-type for the chosen securityType (see the mapping table below).

Conditionally Required Fields

Field Type Description
shareholderEmail string Valid email address of the shareholder. Required when deliveryPreference = "E-Delivery"
shareholderPhysicalAddress object Physical mailing address of the shareholder. Required when deliveryPreference = "Full Set" (see Address Schema)

Optional Fields

Field Type Description
ibdNumber integer or null Introducing broker dealer number (4-digit integer)
txnStatus string or null Free-form transaction status as supplied by the broker
isin string or null ISIN identifier for the security
sedol string or null SEDOL identifier for the security
shareholderHouseholdingFlag boolean or null Householding flag
managerCode string or null Manager code associated with the trade
repCode string or null Representative code associated with the trade
fileId string or null Associated file identifier
type string or null Free-form record type label
parentType string or null Parent record type, when applicable
reasonForCancelation string or null Reason for cancellation, when applicable

Address Schema

The shareholderPhysicalAddress object accepts the following fields. All fields are nullable on their own; however, when deliveryPreference = "Full Set", the addressLine1, city, state, zipCode, and country fields must all be provided.

Field Type Description
addressLine1 string or null Address line 1 (max 100 chars)
addressLine2 string or null Address line 2 (max 100 chars)
city string or null City (max 50 chars)
state string or null State (max 50 chars)
zipCode string or null ZIP code (max 10 chars)
country string or null Country (max 50 chars)

Security Type → Sub-Type Mapping

securitySubType must be a valid sub-type for the chosen securityType. Use the mapping below to determine the allowed combinations.

securityType Allowed securitySubType values
Open-End Fund ETF, Mutual Fund, Money Market Fund, Variable Annuity
UIT ETF, Variable Annuity
Municipal Fund Mutual Fund, ETF, 529
Closed-End Fund Listed CEF
Equities Common Stock, IPO, Preferred Stock, Reg A
Equity Linked Warrants, Rights
Units SPAC
Debt Corporate Bond, Note, Debenture, MTN, ETN, ADR, GO Bond, Revenue Bond
Alternative Investment Commodity ETF, REIT
CD Equity Linked, Index Linked, Fixed, Non-Callable, Step Rate
GSE Bond FNMA, FHLMC, FFCB, FHLB
Federal Agency Bond GNMA, TVA
Unregistered Security Private Placement
REMIC GSE Issued, Privately Issued

Sample Request

Example 1: E-Delivery (with shareholder email)

{
  "tradeDataList": [
    {
      "cusip": "037833100",
      "issuer": "Apple Inc.",
      "tradeDate": "2024-01-15T00:00:00Z",
      "ibdNumber": 1234,
      "brokerTxnId": "TXN-2024-0001",
      "ticker": "AAPL",
      "txnStatus": "NEW",
      "tradeQty": 100,
      "isin": "US0378331005",
      "sedol": "2046251",
      "tradeAction": "BUY",
      "securityType": "Equities",
      "securitySubType": "Common Stock",
      "shareholderAccountNo": "ACC123456",
      "shareholderEmail": "shareholder@yopmail.com",
      "shareholderName": "John Doe",
      "shareholderPhysicalAddress": null,
      "shareholderHouseholdingFlag": false,
      "managerCode": "MGR001",
      "repCode": "REP001",
      "deliveryPreference": "E-Delivery",
      "settlementDate": "2024-01-17T00:00:00Z",
      "brokerId": "507f1f77bcf86cd799439011"
    }
  ]
}

Example 2: Full Set (with physical address)

{
  "tradeDataList": [
    {
      "cusip": "594918104",
      "issuer": "Microsoft Corp.",
      "tradeDate": "2024-01-15T00:00:00Z",
      "ibdNumber": 1234,
      "brokerTxnId": "TXN-2024-0002",
      "ticker": "MSFT",
      "txnStatus": "NEW",
      "tradeQty": 50,
      "isin": "US5949181045",
      "sedol": "2588173",
      "tradeAction": "SELL",
      "securityType": "Equities",
      "securitySubType": "Common Stock",
      "shareholderAccountNo": "ACC654321",
      "shareholderName": "Jane Smith",
      "shareholderPhysicalAddress": {
        "addressLine1": "500 Market St",
        "addressLine2": "Suite 200",
        "city": "San Francisco",
        "state": "CA",
        "zipCode": "94105",
        "country": "USA"
      },
      "shareholderHouseholdingFlag": true,
      "managerCode": "MGR002",
      "repCode": "REP002",
      "deliveryPreference": "Full Set",
      "settlementDate": "2024-01-17T00:00:00Z",
      "brokerId": "507f1f77bcf86cd799439011"
    }
  ]
}

Response

Success Response

{
  "message": "Daily trade data bulk inserted successfully",
  "status": true,
  "data": {
    "status": "success"
  }
}

Status Code: 200

Error Responses

Validation Error

Status Code: 400

{
  "status": false,
  "error": "Validation failed",
  "message": "tradeDataList must contain between 1 and 50 items"
}

Auth Token Error

Status Code: 401

{
  "status": false,
  "error": "Unauthorized",
  "message": "Invalid or missing OAuth token"
}

{
  "message": "Missing required request parameters: [Authorization]"
}

Internal Server Error

Status Code: 500

{
  "status": false,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred while processing the request"
}

Validation Rules

Field Validation

Broker ID

  • Required field
  • Must be a valid 24-character hexadecimal ObjectId

CUSIP

  • Required field
  • CUSIP identifier for the security

Trade Date and Settlement Date

  • tradeDate is required and must be a valid ISO 8601 date-time string in UTC (e.g. "2024-01-15T00:00:00Z")
  • settlementDate is required and must be a valid ISO 8601 date-time string in UTC (e.g. "2024-01-17T00:00:00Z")
  • All date/time values are interpreted as UTC; non-UTC offsets will be rejected

Trade Quantity and Action

  • tradeQty is required and must be greater than or equal to 0
  • tradeAction is required and must be exactly "BUY" or "SELL"

Security Type and Sub-Type

  • securityType is required and must match one of the values in the Security Type → Sub-Type Mapping table
  • securitySubType is required and must be a valid sub-type for the chosen securityType per the mapping table

Delivery Preference

  • deliveryPreference is required and must be exactly "E-Delivery" or "Full Set"
  • When deliveryPreference = "E-Delivery", shareholderEmail is required and must be a valid email address
  • When deliveryPreference = "Full Set", shareholderPhysicalAddress is required, and the addressLine1, city, state, zipCode, and country fields within it must all be provided

Email

  • shareholderEmail, when provided, must follow standard email format: user@domain.com

Address

  • addressLine1: max 100 characters
  • addressLine2: max 100 characters
  • city: max 50 characters
  • state: max 50 characters
  • zipCode: max 10 characters
  • country: max 50 characters

IBD Number

  • ibdNumber, when provided, must be a 4-digit integer

Array Validation

  • tradeDataList must contain between 1 and 50 items
  • Each item must pass individual validation
  • Records are deduplicated downstream on the compound key cusip | tradeDate | shareholderAccountNo

Error Handling

Common Error Responses

Invalid Trade Action

{
  "status": false,
  "error": "Validation failed",
  "message": "Trade action must be either BUY or SELL"
}

Invalid Security Sub-Type

{
  "status": false,
  "error": "Validation failed",
  "message": "securitySubType is not valid for the given securityType"
}

Missing Required Fields

{
  "status": false,
  "error": "Validation failed",
  "message": "CUSIP is required"
}

Invalid Settlement Date Format

{
  "status": false,
  "error": "Validation failed",
  "message": "Settlement date must be in ISO 8601 format"
}

Trade Data List Over Limit

{
  "status": false,
  "error": "Validation failed",
  "message": "Maximum 50 trade data items allowed per request"
}

Trade Data List Empty

{
  "status": false,
  "error": "Validation failed",
  "message": "At least one trade data item is required"
}

shareholderEmail Required for E-Delivery

{
  "status": false,
  "error": "Validation failed",
  "message": "shareholderEmail is required when deliveryPreference is E-Delivery"
}

shareholderPhysicalAddress Required for Full Set

{
  "status": false,
  "error": "Validation failed",
  "message": "shareholderPhysicalAddress with addressLine1, city, state, zipCode, and country is required when deliveryPreference is Full Set"
}

Invalid Email Format

{
  "status": false,
  "error": "Validation failed",
  "message": "Please provide a valid email address"
}

Implementation Examples

cURL Example

curl -X POST "https://shareholders-api-dev.govotr.com/api/v1/trade" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE" \
  -d '{
    "tradeDataList": [
      {
        "cusip": "037833100",
        "issuer": "Apple Inc.",
        "tradeDate": "2024-01-15T00:00:00Z",
        "brokerTxnId": "TXN-2024-0001",
        "ticker": "AAPL",
        "tradeQty": 100,
        "tradeAction": "BUY",
        "securityType": "Equities",
        "securitySubType": "Common Stock",
        "shareholderAccountNo": "ACC123456",
        "shareholderEmail": "shareholder@yopmail.com",
        "shareholderName": "John Doe",
        "deliveryPreference": "E-Delivery",
        "settlementDate": "2024-01-17T00:00:00Z",
        "brokerId": "507f1f77bcf86cd799439011"
      }
    ]
  }'

JavaScript/Node.js Example

const tradeData = {
  tradeDataList: [
    {
      cusip: "594918104",
      issuer: "Microsoft Corp.",
      tradeDate: "2024-01-15T00:00:00Z",
      ibdNumber: 1234,
      brokerTxnId: "TXN-2024-0002",
      ticker: "MSFT",
      txnStatus: "NEW",
      tradeQty: 50,
      isin: "US5949181045",
      sedol: "2588173",
      tradeAction: "SELL",
      securityType: "Equities",
      securitySubType: "Common Stock",
      shareholderAccountNo: "ACC654321",
      shareholderName: "Jane Smith",
      shareholderPhysicalAddress: {
        addressLine1: "500 Market St",
        addressLine2: "Suite 200",
        city: "San Francisco",
        state: "CA",
        zipCode: "94105",
        country: "USA",
      },
      shareholderHouseholdingFlag: true,
      managerCode: "MGR002",
      repCode: "REP002",
      deliveryPreference: "Full Set",
      settlementDate: "2024-01-17T00:00:00Z",
      brokerId: "507f1f77bcf86cd799439011",
    },
  ],
}

try {
  const response = await fetch(
    "https://shareholders-api-dev.govotr.com/api/v1/trade",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer YOUR_ACCESS_TOKEN_HERE",
      },
      body: JSON.stringify(tradeData),
    },
  )

  const result = await response.json()

  if (response.ok) {
    console.log("Trade data submitted successfully:", result)
  } else {
    console.error("Error submitting trade data:", result)
  }
} catch (error) {
  console.error("Network error:", error)
}

Python Example

import requests

def submit_trade_data():
    url = "https://shareholders-api-dev.govotr.com/api/v1/trade"

    payload = {
        "tradeDataList": [
            {
                "cusip": "037833100",
                "issuer": "Apple Inc.",
                "tradeDate": "2024-01-15T00:00:00Z",
                "ibdNumber": 1234,
                "brokerTxnId": "TXN-2024-0001",
                "ticker": "AAPL",
                "txnStatus": "NEW",
                "tradeQty": 100,
                "isin": "US0378331005",
                "sedol": "2046251",
                "tradeAction": "BUY",
                "securityType": "Equities",
                "securitySubType": "Common Stock",
                "shareholderAccountNo": "ACC123456",
                "shareholderEmail": "shareholder@yopmail.com",
                "shareholderName": "John Doe",
                "shareholderHouseholdingFlag": False,
                "managerCode": "MGR001",
                "repCode": "REP001",
                "deliveryPreference": "E-Delivery",
                "settlementDate": "2024-01-17T00:00:00Z",
                "brokerId": "507f1f77bcf86cd799439011"
            }
        ]
    }

    headers = {
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
    }

    try:
        response = requests.post(url, json=payload, headers=headers)

        if response.status_code == 200:
            result = response.json()
            print("Trade data submitted successfully:", result)
            return result
        else:
            print(f"Error: {response.status_code}")
            print(response.text)
            return None

    except requests.exceptions.RequestException as e:
        print(f"Network error: {e}")
        return None

# Usage
submit_trade_data()

Best Practices

Data Quality

  • Validate data before submission to avoid API errors
  • Use consistent formatting for account numbers and CUSIP codes
  • Provide complete address information when delivering to a physical address
  • Include shareholder contact details (email or address) for proper delivery routing
  • Confirm securityType / securitySubType combinations are valid before submission

Performance

  • Batch submissions up to 50 records per request for efficiency
  • Implement retry logic for failed requests
  • Use appropriate timeouts for network requests
  • Log request/response data for debugging

Security

  • Validate input data on your server before forwarding to VOTR
  • Use HTTPS for all API communications
  • Store sensitive data securely and follow data protection regulations
  • Avoid logging full payloads containing PII (names, emails, addresses)

Error Handling

  • Check response status codes before processing responses
  • Implement exponential backoff for retry attempts
  • Log brokerTxnId values alongside errors for traceability
  • Provide meaningful error messages to end users

Next Steps: After successfully implementing the trades endpoint, you can integrate the Shareholders Endpoint for shareholder data submission and the Voting URL API to enable voting functionality for the submitted shareholders.