Voting

When a shareholder clicks "Vote Now", call this endpoint to get a hosted voting URL. Pass the URL to the VoteNowButton SDK; VOTR hosts the ballot and records the vote.

Request

GET /events/{eventId}/ballot takes the event ID in the path, two required query parameters and one optional one.

Parameter	In	Required	Description
eventId	path	Yes	The event's 24-character hex ID, from Events.
accountNo	query	Yes	The shareholder's account number.
brokerId	query	Yes	Your 24-character hex broker ID.
cusipNo	query	No	The CUSIP of the holding to vote on. Send it when you submitted the same accountNo for more than one CUSIP of the issuer in this event.

accountNo must equal the accountNo you sent in the Shareholders request for this event. The lookup is an exact match. If that account was submitted under two CUSIPs, add cusipNo so VOTR returns the ballot for the right holding; without it the first matching record is used.

Example request

curl "https://api-stage.govotr.com/broker/v1/events/64f8a1b2c3d4e5f6a7b8c9d0/ballot?accountNo=ACC123456&brokerId=681a3f923b07005fdc5b5417" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

200 response

{
  "message": "Data retrieved successfully",
  "status": true,
  "data": {
    "url": "https://vote.govotr.com/public-voting-screen?id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&isInApp=true"
  }
}

Open data.url for the shareholder, either with the VoteNowButton SDK or any way you like.

Errors

Every error body is { "status": false, "error": "<message>" }.

Status	What it means	What to do
400	A parameter is missing or malformed. Passing email also returns 400 with Not a valid query parameter. Please use accountNo.	Send both accountNo and brokerId. Check eventId and brokerId are 24-character hex IDs.
401	The Bearer token is missing, expired or invalid.	Get a new token from Authentication.
403	The shareholder does not belong to the brokerId you sent.	Use the same brokerId you used in the shareholders request.
404	The event does not exist, is not a Proxy event, or accountNo (with cusipNo, if sent) was not submitted for it.	Check the eventId, the event's eventType, and that the account number and CUSIP are exactly the values you submitted.
423	Voting is not open. Either final documents are not confirmed yet or the voting period has ended.	Call event details first and only show "Vote Now" when votingLinksActive is true.
429	Rate limit hit: 5,000 requests per 5 minutes per IP address across all /broker/v1 routes.	Back off and retry.

Tips

• The event must be a Proxy event in active voting. Confirm with Events before requesting a URL — you'll get 423 Locked otherwise.
• Request a fresh URL on every "Vote Now" tap. Do not generate it at page load, and do not cache or reuse it.
• accountNo and brokerId must match the shareholders submission exactly. An account that was not submitted for this event returns 404. A brokerId different from the one it was submitted under returns 403.
• One account, two CUSIPs: pass cusipNo. If you sent one record per CUSIP for the same account, the ballot URL is per holding. Send the CUSIP the shareholder tapped on.

Loading playground…