VOTE API · OWNER GUIDE

Reward verified votes safely

Create a short-lived vote session from your server, send the player to Toplands, then claim the verified vote exactly once before granting the reward.

View quick start Open dashboard

Implementation statusThe integration contract is documented here. Production keys and test mode will be issued from each approved server in the owner dashboard.

How vote validation works

A protected flow from your game server to the player and back.

Create a vote session

Your backend sends a private player reference and receives a short-lived vote URL.

Open the vote page

Your launcher, website or in-game command opens the returned URL in the player's browser.

Complete the vote

Toplands applies captcha, eligibility checks and the 24-hour cooldown before recording it.

Claim and reward

Your backend validates the result and atomically claims the vote once.

Quick start

The recommended pattern for a launcher, account panel or in-game vote command.

STEP 1

Create a vote session from your backend

Use an opaque player identifier. Never send passwords, e-mail addresses or character data Toplands does not need.

POST/v1/vote-sessions

curl -X POST https://api.toplands.com/v1/vote-sessions \
  -H "Authorization: Bearer YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"srv_aden_01","player_reference":"account_18427"}'

STEP 2

Open the returned vote URL

The URL may be opened from a launcher button, account panel or an in-game command. The client never receives the secret API key.

window.open(voteSession.vote_url, "_blank", "noopener,noreferrer");

STEP 3

Check whether the vote was verified

Poll only while pending, then stop after completion, expiration or failure.

GET/v1/vote-sessions/{session_id}

{"status":"verified","vote_id":"vote_51ad7b","next_vote_at":"2026-10-22T20:42:18Z","claimed":false}

STEP 4

Claim once, then grant the reward

Claiming must be atomic and idempotent. Only a response with claimed: true authorizes the reward.

POST/v1/votes/{vote_id}/claim

Safe order

Claim at Toplands, save a local reward log, then credit the player.

Implementation rules

These rules protect the player and your reward economy.

Keep keys server-side

Never embed a secret in JavaScript, HTML, a launcher executable or the game client.

Use opaque references

Send an internal ID or server-generated alias instead of personal information.

Reward after claim

A success page is not proof. Trust only the authenticated API response.

Respect cooldowns

Use next_vote_at to show the next eligible time and avoid unnecessary calls.

Integration lives with the server

The dashboard generates the vote URL and embed code with the correct server ID. Secret keys remain separate and server-side.

Open owner dashboard