Shareholders Endpoint

Complete documentation for the VOTR Shareholders API endpoint

📚 Interactive API Documentation

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

🔗 Shareholders 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: shareholders-api-spec.yaml

� Shareholders Data Submission

The Shareholders endpoint allows brokers to submit shareholder data for specific events. This endpoint is used to upload shareholder information including contact details, shareholdings, and voting preferences.

API Endpoints

Development:

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

Production:

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

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Note: This endpoint uses the same OAuth 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
brokerId string ✅ 24-character hexadecimal broker ID
eventId string ✅ 24-character hexadecimal event ID
data array ✅ Array of shareholder data (1-50 items)

Data Item Schema

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

Required Fields

Field Type Description
totalShares number Number of shares (0.000001 - 999,999,999, up to 6 decimals)
accountNo string Account number (1-50 alphanumeric chars)
cusipNo string CUSIP number (exactly 9 alphanumeric chars)
preferredVoting string Voting preference ("E-Delivery" or "Full Set")

Important:

  • Either email OR address (or both) must be provided. If neither is provided, the request will fail with a validation error.
  • naaPreference is conditionally required based on the preferredVoting designation.
  • While name and noboObo are optional, it is highly encouraged that these fields are included for proper shareholder identification and preference tracking.
  • If noboObo is not provided, shareholders will default to OBO (Objecting Beneficial Owner) status.

Conditionally Required Fields

Field Type Description
naaPreference boolean NAA preference setting (required based on preferredVoting designation)

Optional Fields

Field Type Description
name string or null Shareholder name (max 100 chars). Highly encouraged to include for proper identification.
noboObo string or null NOBO/OBO status ("nobo" or "obo"). Highly encouraged to include. Defaults to "obo" if omitted.
email string or null Valid email address (max 255 chars). Either email or address must be provided.
managerCode string or null Manager code (1-50 alphanumeric chars)
repCode string or null Rep code (1-50 alphanumeric chars)
ibdNumber string or null IBD number (1-50 alphanumeric chars)
householdingFlag string or null Householding flag setting (string value)
introBrokerName string or null Introducing broker name (1-100 chars)
isin string or null International Securities Identification Number (1-50 chars)
proxyFlag boolean or null Proxy flag (default false)
address object or null Address object (see Address Schema). Either email or address must be provided.

Address Schema

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 100 chars)
zipCode string or null ZIP code (max 100 chars)
country string or null Country (max 50 chars)

Sample Request

Example 1: With Email

{
  "brokerId": "681a3f923b07005fdc5b5417",
  "eventId": "688a009f3b699e129a64513b",
  "data": [
    {
      "totalShares": 100.5,
      "accountNo": "ACC123456",
      "cusipNo": "037833100",
      "email": "john.doe@example.com",
      "name": "John Doe",
      "noboObo": "nobo",
      "preferredVoting": "E-Delivery",
      "naaPreference": true,
      "managerCode": "MGR001",
      "repCode": "REP123",
      "ibdNumber": "IBD123456",
      "householdingFlag": "true",
      "introBrokerName": "ABC Securities",
      "isin": "US0378331005",
      "proxyFlag": false
    }
  ]
}

Example 2: With Address

{
  "brokerId": "681a3f923b07005fdc5b5417",
  "eventId": "688a009f3b699e129a64513b",
  "data": [
    {
      "totalShares": 250.75,
      "accountNo": "ACC789012",
      "cusipNo": "68389X105",
      "address": {
        "addressLine1": "456 Oak Avenue",
        "addressLine2": "Suite 200",
        "city": "Los Angeles",
        "state": "CA",
        "zipCode": "90210",
        "country": "USA"
      },
      "name": "Jane Smith",
      "noboObo": "obo",
      "preferredVoting": "Full Set",
      "introBrokerName": "XYZ Brokers",
      "isin": "US5949181045",
      "proxyFlag": true
    }
  ]
}

Response

Success Response

{
  "SendMessageResponse": {
    "ResponseMetadata": {
      "RequestId": "af15a64f-0a6c-5058-9fc3-c73ddbbe2b66"
    },
    "SendMessageResult": {
      "MD5OfMessageAttributes": null,
      "MD5OfMessageBody": "e465a41bb78e2b21f614e77566871238",
      "MD5OfMessageSystemAttributes": null,
      "MessageId": "8fd668bd-66bd-4fb4-94d5-697efe5b67d2",
      "SequenceNumber": null
    }
  }
}

Response Fields

Field Type Description
RequestId string Unique identifier for the request
MD5OfMessageBody string MD5 hash of the message body
MessageId string Unique identifier for the message
MD5OfMessageAttributes null MD5 hash of message attributes
MD5OfMessageSystemAttributes null MD5 hash of system attributes
SequenceNumber null Sequence number (if applicable)

Validation Rules

Field Validation

Broker and Event IDs

  • Must be exactly 24 characters
  • Must contain only hexadecimal characters (a-f, 0-9)
  • Case sensitive (lowercase only)

Email and Address Validation

  • Either email OR address must be provided (or both)
  • If neither is provided, validation will fail
  • Email must follow standard email format: user@domain.com
  • Email maximum 255 characters
  • Address object can be null if email is provided

Account Number

  • 1-50 alphanumeric characters
  • Case insensitive
  • Required field

CUSIP Number

  • Exactly 9 alphanumeric characters
  • Uppercase letters and numbers only
  • Required field

Total Shares

  • Minimum value: 0.0001
  • Maximum value: 999,999,999
  • Must be a positive number

Array Validation

  • data array must contain 1-50 items
  • Each item must pass individual validation
  • No duplicate account numbers within the same request

Error Handling

Common Error Responses

Invalid Broker ID

{
  "error": "Invalid brokerId format",
  "message": "brokerId must be a 24-character hexadecimal string"
}

Invalid Data Array

{
  "error": "Invalid data array",
  "message": "data array must contain between 1 and 100 items"
}

Missing Required Fields

{
  "error": "Validation failed",
  "message": "Missing required field: totalShares"
}

Invalid Email Format

{
  "error": "Invalid email format",
  "message": "email must be a valid email address or null"
}

Missing Email or Address

{
  "error": "Validation failed",
  "message": "Either email or address must be provided"
}

Implementation Examples

cURL Example

curl -X POST "https://shareholders-api-dev.govotr.com/api/v1/shareholders" \
  -H "Content-Type: application/json" \
  -d '{
    "brokerId": "681a3f923b07005fdc5b5417",
    "eventId": "688a009f3b699e129a64513b",
    "data": [
      {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "totalShares": 100.5,
        "accountNo": "ACC123456",
        "cusipNo": "037833100",
        "noboObo": "nobo",
        "preferredVoting": "E-Delivery",
        "address": {
          "addressLine1": "123 Main St",
          "city": "New York",
          "state": "NY",
          "zipCode": "10001",
          "country": "USA"
        }
      }
    ]
  }'

JavaScript/Node.js Example

const shareholderData = {
  brokerId: "681a3f923b07005fdc5b5417",
  eventId: "688a009f3b699e129a64513b",
  data: [
    {
      name: "Jane Smith",
      email: "jane.smith@example.com",
      totalShares: 250.75,
      accountNo: "ACC789012",
      cusipNo: "594918104",
      noboObo: "obo",
      preferredVoting: "Full Set",
      naaPreference: true,
      managerCode: "MGR001",
      repCode: "REP123",
      ibdNumber: "IBD123456",
      householdingFlag: "true",
      introBrokerName: "ABC Securities",
      isin: "US0378331005",
      proxyFlag: false,
      address: {
        addressLine1: "456 Oak Avenue",
        addressLine2: "Suite 200",
        city: "Los Angeles",
        state: "CA",
        zipCode: "90210",
        country: "USA",
      },
    },
  ],
}

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

  const result = await response.json()

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

Python Example

import requests
import json

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

    data = {
        "brokerId": "681a3f923b07005fdc5b5417",
        "eventId": "688a009f3b699e129a64513b",
        "data": [
            {
                "name": "Alice Johnson",
                "email": "alice.johnson@example.com",
                "totalShares": 500.0,
                "accountNo": "ACC345678",
                "cusipNo": "68389X105",
                "noboObo": "nobo",
                "preferredVoting": "E-Delivery",
                "managerCode": "MGR001",
                "repCode": "REP123",
                "ibdNumber": "IBD456789",
                "householdingFlag": "false",
                "introBrokerName": "XYZ Brokers",
                "isin": "US5949181045",
                "proxyFlag": true,
                "address": {
                    "addressLine1": "789 Pine Street",
                    "city": "Chicago",
                    "state": "IL",
                    "zipCode": "60601",
                    "country": "USA"
                }
            }
        ]
    }

    headers = {
        "Content-Type": "application/json"
    }

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

        if response.status_code == 200:
            result = response.json()
            print("Shareholders 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_shareholders_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 available
  • Include email addresses for better shareholder communication

Performance

  • Batch submissions up to 100 shareholders 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
  • Implement proper error handling to avoid exposing sensitive information

Error Handling

  • Check response status codes before processing responses
  • Implement exponential backoff for retry attempts
  • Log errors appropriately for monitoring and debugging
  • Provide meaningful error messages to end users

Next Steps: After successfully implementing the shareholders endpoint, you can proceed to integrate with the Voting URL API to enable voting functionality for the submitted shareholders.