Developer reference

LuckyFinder URL API

Open a prepared draw from another site: URL parameters, a share token, hosted CSV, inline CSV data, and a postMessage handoff, with limits and code samples.

A linking page builds a URL, or opens the app and sends a message. The app parses names, labels and settings in the browser; there is no API key and no backend.

List delivery methods

  • Names in the query: one name per parameter, or a pipe-separated names value, up to 500 entries.
  • Share token: a base64url JSON payload after #setup, written by the Share panel.
  • Hosted CSV: an HTTPS URL that allows CORS, parsed locally, with unique and display column hints.
  • Inline CSV: the CSV text itself, base64url encoded under csvdata. No hosting and no CORS.
  • postMessage: a page that opens the app can send up to 20,000 rows after the luckyfinder:ready message.

Query parameters

  • campaign Campaign name shown above the wheel. Up to 120 characters.
  • prize Prize label printed under the campaign name.
  • name One participant per occurrence, up to 500 names.
  • names A pipe-separated list in a single parameter.
  • palette A wheel palette id. Use custom together with colors for your own colours.
  • colors Three hex colours, comma separated and URL-encoded.
  • theme light or dark.
  • csv HTTPS URL of a CSV that allows CORS. Downloaded and parsed in the browser.
  • csvdata Base64url CSV text carried inside the link, under 60,000 characters.
  • unique Header used as the unique key for CSV lists.
  • display Header printed on the wheel for CSV lists.
  • autostart 1 loads the built-in sample list for demos.
  • #setup Base64url JSON token with settings and participant rows.

Example

https://luckyfinder.pages.dev/?campaign=Launch+Night&prize=Gold&name=Aung+Ko+Ko&name=Su+Myat+Noe&theme=dark

A link that carries participants opens the Wheel Stage. A link that carries only settings opens the participant step with those settings ready.

Privacy

Anything in a link is readable by whoever holds it. Use a hosted CSV, inline CSV or a postMessage handoff when the list contains personal data. Winner records stay encrypted in the browser.

LuckyFinderUser guideTerms of ServicePrivacy Policy

The interactive reference requires JavaScript.