Event Voting Status API

Check voting availability and status for specific events

🗳️ Event Voting Status

Get the current voting status and availability information for a specific event. This endpoint allows brokers to check whether voting is currently active and available for an event.

Note: This endpoint is optional and not required for basic voting functionality. Use it to provide enhanced UI experience by checking voting availability before presenting options to shareholders.

API Endpoints

Development:

GET https://api-dev.govotr.com/api/v1/event/{eventId}

Production:

GET https://api.govotr.com/api/v1/event/{eventId}

Authentication

This endpoint uses the same OAuth authentication flow as other VOTR APIs.

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

📋 For OAuth token generation, refer to: OAuth Token Documentation

Path Parameters

Parameter Type Required Description
eventId string ✅ Unique identifier for the event (ObjectId)

Parameter Details

Event ID Parameter

  • Format: 24-character hexadecimal MongoDB ObjectId
  • Pattern: ^[0-9a-fA-F]{24}$
  • Required: Yes
  • Example: 64f8a1b2c3d4e5f6a7b8c9d0

Query Parameters

Parameter Type Required Description
cusip string ❌ Optional CUSIP number to filter by specific security

Parameter Details

CUSIP Parameter

  • Format: String
  • Required: No
  • Purpose: Filter the event by specific security CUSIP
  • Example: 037833100

Use Cases

  • Check Voting Availability: Determine if voting links are currently active
  • Event Status Verification: Get current event status (Active, Upcoming, Expired, Cancelled)
  • Timeline Information: Retrieve voting open date/time and deadline
  • UI Enhancement: Verify event details before presenting to shareholders
  • Status Polling: Monitor when voting becomes available

Event Status Values

Status Description
Active Event is currently accepting votes
Upcoming Event has not started yet (status = 1)
Expired Voting period has ended (status = 3)
Cancelled Event has been cancelled (status = 5)

The votingLinksActive field indicates whether shareholders can currently vote:

  • true: Voting is open and links are functional
  • false: Voting is not available (event not started, ended, or cancelled)

Conditions for Active Voting Links:

  • Final documents are confirmed (confirmFinalDocuments = true)
  • Event status is Active (status = 2)
  • Current time is before the voting deadline

Response Caching

Responses are cached with dynamic TTL for optimal performance:

Event State Cache Duration
Active Events Cached until voting ends (minimum 60 seconds)
Expired/Cancelled Cached for 24 hours
Default 1 hour

Cache Auto-Clear Triggers:

  • Event details are updated
  • Event status changes
  • Ballots are modified
  • Mailing status is updated

Response Format

Success Response

{
  "message": "Event voting status retrieved successfully",
  "status": true,
  "data": {
    "eventId": "64f8a1b2c3d4e5f6a7b8c9d0",
    "cusip": "037833100",
    "isin": ["US1234567890", "US0987654321"],
    "ticker": ["AAPL", "MSFT"],
    "recordDate": "2024-01-15",
    "meetingDate": "2024-02-15",
    "meetingTime": "10:00 AM",
    "votingOpenDateTime": "2024-01-16T09:00:00.000Z",
    "votingDeadline": "2024-02-14T23:59:59.000Z",
    "eventStatus": "Active",
    "votingLinksActive": true
  }
}

Response Schema

Main Response Object

Field Type Description
message string Success message
status boolean Request status (true for success)
data object Event voting status data

Data Object

Field Type Description
eventId string Unique identifier for the event
cusip string CUSIP number (if provided in request), nullable
isin array Array of ISIN (International Securities Identification Number) for matching child issuers, nullable
ticker array Array of ticker symbols for matching child issuers, nullable
recordDate string Record date (YYYY-MM-DD, ET timezone), nullable
meetingDate string Meeting date (YYYY-MM-DD, ET timezone), nullable
meetingTime string Meeting time (ET timezone), nullable
votingOpenDateTime string ISO 8601 timestamp when voting became available (when first email was delivered). Null if no emails delivered.
votingDeadline string ISO 8601 timestamp for voting end date and time
eventStatus string Current event status (Active, Upcoming, Expired, Cancelled)
votingLinksActive boolean Whether voting links are currently active and functional

Usage Examples

Get Event Voting Status by Event ID

curl -X GET "https://api-dev.govotr.com/api/v1/event/64f8a1b2c3d4e5f6a7b8c9d0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Get Event Voting Status with CUSIP Filter

curl -X GET "https://api-dev.govotr.com/api/v1/event/64f8a1b2c3d4e5f6a7b8c9d0?cusip=037833100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

JavaScript/Node.js Example

async function getEventVotingStatus(accessToken, eventId, cusip = null) {
  try {
    const url = new URL(`https://api-dev.govotr.com/api/v1/event/${eventId}`)

    if (cusip) {
      url.searchParams.append("cusip", cusip)
    }

    const response = await fetch(url.toString(), {
      method: "GET",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json",
      },
    })

    const data = await response.json()

    if (data.status) {
      console.log("Event voting status:", data.data)

      // Check if voting is available
      if (data.data.votingLinksActive) {
        console.log("✅ Voting is currently active!")
        console.log(`Voting deadline: ${data.data.votingDeadline}`)
      } else {
        console.log(
          `❌ Voting not available. Event status: ${data.data.eventStatus}`
        )
      }

      return data.data
    } else {
      console.error("Error retrieving event status:", data.error)
      return null
    }
  } catch (error) {
    console.error("Network error:", error)
    return null
  }
}

// Usage examples
const accessToken = "your_access_token_here"
const eventId = "64f8a1b2c3d4e5f6a7b8c9d0"

// Get event status
getEventVotingStatus(accessToken, eventId)

// Get event status with CUSIP filter
getEventVotingStatus(accessToken, eventId, "037833100")

Python Example

import requests
from datetime import datetime

def get_event_voting_status(access_token, event_id, cusip=None):
    """
    Retrieve voting status for a specific event
    """
    url = f"https://api-dev.govotr.com/api/v1/event/{event_id}"

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

    params = {}
    if cusip:
        params["cusip"] = cusip

    try:
        response = requests.get(url, headers=headers, params=params)

        if response.status_code == 200:
            data = response.json()
            if data.get("status"):
                event_data = data["data"]
                print(f"Event Status: {event_data['eventStatus']}")

                if event_data["votingLinksActive"]:
                    print("✅ Voting is currently active!")
                    print(f"Voting deadline: {event_data['votingDeadline']}")
                else:
                    print(f"❌ Voting not available. Status: {event_data['eventStatus']}")

                return event_data
            else:
                print(f"Error: {data.get('error', 'Unknown error')}")
                return None
        elif response.status_code == 404:
            print(f"Event not found: {event_id}")
            return None
        else:
            print(f"HTTP Error: {response.status_code}")
            print(response.text)
            return None

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

# Usage examples
access_token = "your_access_token_here"
event_id = "64f8a1b2c3d4e5f6a7b8c9d0"

# Get event status
event_status = get_event_voting_status(access_token, event_id)

# Get event status with CUSIP filter
event_status_with_cusip = get_event_voting_status(access_token, event_id, "037833100")

Error Handling

Common Error Responses

400 - Bad Request

Invalid Event ID format:

{
  "status": false,
  "error": "Event ID must be a valid ObjectId"
}

Missing Event ID:

{
  "status": false,
  "error": "Event ID is required"
}

Invalid CUSIP type:

{
  "status": false,
  "error": "CUSIP must be a string"
}

401 - Unauthorized

Invalid or missing OAuth token:

{
  "status": false,
  "error": "Authorization header is required"
}

404 - Not Found

Event not found:

{
  "status": false,
  "error": "Event not found for the provided Event ID"
}

Event not found with CUSIP:

{
  "status": false,
  "error": "Event not found for the provided Event ID and CUSIP"
}

500 - Internal Server Error

Server error:

{
  "status": false,
  "error": "Internal server error"
}

Best Practices

Polling Strategy

  • Check before presenting UI: Verify voting is active before showing “Vote Now” button
  • Implement smart polling: Poll more frequently as voting deadline approaches
  • Cache responses: Leverage the built-in caching mechanism
  • Handle status transitions: Update UI when event status changes

Error Handling

  • Validate Event ID format: Ensure Event ID matches ObjectId pattern before API call
  • Handle 404 gracefully: Event may not exist or may be filtered out by CUSIP
  • Implement retry logic: Handle transient failures with exponential backoff
  • Log errors appropriately: Monitor API usage and error patterns

Performance

  • Use caching: Respect cache headers to reduce unnecessary API calls
  • Batch checks: If checking multiple events, space out requests appropriately
  • Monitor response times: Track API performance for your use case

UI/UX

  • Display event status: Show clear status indicators (Active, Upcoming, Expired)
  • Show voting timeline: Display voting open date/time and deadline to users
  • Disable when inactive: Disable “Vote Now” button when votingLinksActive is false
  • Provide context: Explain why voting is not available (upcoming, expired, cancelled)

Integration Workflow

This endpoint fits into the overall integration workflow:

  1. Broker retrieves events using Events API
  2. Broker submits shareholder data via Shareholders API
  3. Broker checks voting status using this endpoint ← You are here
  4. When votingLinksActive is true, broker can request Voting URL
  5. Shareholder completes vote through SDK