Event Details API

📋 Event Details

Get detailed information and voting status for a specific event. This endpoint allows brokers to retrieve comprehensive event details including voting availability, event status, and timeline information.

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, Cancelled, Completed)
• 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
Upcoming	Event has not started yet
Active	Event is currently accepting votes
Cancelled	Event has been cancelled
Completed	Event has been completed

---

Voting Links Active

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
• Current time is before the voting deadline

---

Response Format

Success Response

{
  "message": "Event voting status retrieved successfully",
  "status": true,
  "data": {
    "eventId": "64f8a1b2c3d4e5f6a7b8c9d0",
    "cusip": ["037833100"],
    "isin": ["US1234567890", "US0987654321"],
    "ticker": ["AAPL", "MSFT"],
    "recordDate": "2026-01-31",
    "meetingDate": "2026-02-26T00:30:00.000Z",
    "votingOpenDateTime": null,
    "votingDeadline": null,
    "shareholderReportingDeadline": "2026-01-31T01:00:00.000Z",
    "eventStatus": "Active",
    "votingLinksActive": null
  }
}

Response Schema

Main Response Object

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

Data Object

Field	Type	Description
eventId	string	Unique identifier for the event
cusip	string	CUSIP number (if provided in request), nullable
isin	string[]	Array of ISIN (International Securities Identification Number) for matching child issuers, nullable
ticker	string[]	Array of ticker symbols for matching child issuers, nullable
recordDate	string	Record date in YYYY-MM-DD format (ET-based event date).
meetingDate	string	ISO 8601 timestamp for meeting date. May be an empty string when not available.
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 (ET timezone). May be null.
shareholderReportingDeadline	string	ISO 8601 timestamp (ET) by which shareholder information must be submitted to capture and process issuer communications
eventStatus	string	Current event status. One of: Active, Upcoming, Cancelled, Completed.
votingLinksActive	boolean	Whether voting links are currently active and functional. May be null.

---

Usage Examples

Get Event Details 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 Details 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 getEventDetails(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 details:", 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 details
getEventDetails(accessToken, eventId)

// Get event details with CUSIP filter
getEventDetails(accessToken, eventId, "037833100")

Python Example

import requests
from datetime import datetime

def get_event_details(access_token, event_id, cusip=None):
    """
    Retrieve event details 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 details
event_details = get_event_details(access_token, event_id)

# Get event details with CUSIP filter
event_details_with_cusip = get_event_details(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, Cancelled, Completed)
• 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 (upcomin, cancelled, completed)

---

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 retrieves event details using this endpoint ← You are here
4. When votingLinksActive is true, broker can request Voting URL
5. Shareholder completes vote through SDK

---

Related Documentation

• Events API Reference
• Voting URL API Reference
• Shareholders Endpoint Reference
• Integration Workflow
• Troubleshooting Guide