> ## Documentation Index
> Fetch the complete documentation index at: https://veriqa.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Honest voting on any website

> A vote confirmed in the voter's messenger and a result that can be checked: what the product already has for it, what is still missing and where the scenario's limits are.

Online votes — a fan favorite, a contest, an award — are too often decided by whoever bought the
votes. Paid services solve CAPTCHAs, an email address costs nothing, and a social account
is cheap. The organizer has nothing to answer an accusation with but
a promise.

The scenario is a voting widget that can be embedded on any website. Every vote is a Veriqa
confirmation in the voter's messenger — one tap, with no sign-up, no password and no code to
type — and the result comes with a signed receipt that the voter and a third party can check. In
one line: a vote whose result can be shown, not just promised.

<Note>
  You build the core of this scenario yourself from mechanisms Veriqa already provides; what is still
  missing is listed below. We are working on making it simpler to implement in the product.
</Note>

## What it is for

* **The voter** votes without an account, and the receipt lets them check that their vote is in
  the total.
* **The nominee** gets a win that can be proved. A victory nobody can verify is worth little once
  someone says it was bought.
* **The organizer** moves from "trust us" to "check for yourself", and does not have to store
  phone numbers to fight fraud.
* **The sponsor** gets a result that can be audited, and reach measured in people rather than
  clicks.
* **The site developer** embeds a widget instead of building verification, number storage and
  their own anti-fraud.

A campaign that runs in several networks at once gets one more thing. Today the votes from each
network are added up, and the same person counts once per network. A phone number is the one
identifier all the networks share: if the posts in every network lead to one ballot, one person is
one vote whatever the entry point, and the organizer sees how many unique people each network
brought and how far the audiences overlap. The cost is one extra step: a poll built into the
network itself — a channel poll or a Stories sticker — has nowhere to put a confirmation.

## How strong the protection is

No anti-fraud is perfect, and the scenario does not claim immunity. It claims fraud that is
**more expensive** than with the methods common on websites today: a CAPTCHA or an email
confirmation costs a fraud farm next to nothing, a social account is cheap, and an identity
anchored to a phone number costs more than a social account.

SMS verification uses the same anchor, and against it the protection is on par. The difference
lies elsewhere: the voter does not retype a code, and messages are not billed per message. In
WhatsApp, Veriqa replies to the user's message without a template, and under Meta's current
pricing such replies are free. The same trade-off as in [Replacing SMS codes](/docs/scenarios/sms-replacement): the phone anchor
at the price of a messenger wherever the audience has one.

## What it builds on

A vote is not a separate product but a confirmation of an action carrying data — which poll and
which choice. That transaction already exists:

1. **Server-to-server confirmation.** The website's server calls
   `POST /api/transaction/confirmation` with a declared action type (`action_type`) and receives
   the channel's deep link and a QR code for the voter. The outcome is read with
   `GET /api/transaction/{id}/result` — `confirmed`, `declined`, `expired` or `failed` — and the
   response does not disclose who confirmed.
2. **The exact subject in the message.** The poll and the choice travel in typed slots
   (`slot_values`) against the schema of the action type, and the voter sees in the chat what they
   are voting for, with Confirm and Decline buttons.
3. **The phone number as the key.** WhatsApp delivers `phone_number` — with the message, or through
   the phone step when the user hides the number behind a username. Telegram hands over an account
   identifier rather than a number — see the [channel catalog](/docs/guides/supported-channels).
4. **The audit trail.** The trail is append-only; a deployment can explicitly turn on recording
   the parameters of the confirmed operation, and user identifiers appear in it only masked.

## What does not exist today

* **One person — one vote.** The product confirms an action but neither counts votes nor
  deduplicates them within a poll.
* **A key that does not keep the number.** Deduplication needs the phone, but the record should
  hold a one-way keyed hash, different for every poll, rather than the number itself — the
  approach described in [Resilience to a personal-data leak](/docs/scenarios/leak-resilience). In
  Telegram the number is available only after the user explicitly shares it.
* **A signed receipt and a checkable total.** The voter needs a receipt, and the poll a published
  summary against which the voter checks that their vote is included and a third party checks that
  the total matches the register. The message Veriqa sends after a confirmation is text for the
  user, not an attestation, and the audit trail is not tamper-evident.
* **The anchor level as a property of the poll.** Not a "protected" badge but "collected on an
  anchor costing about this much per identity", together with the checks around the key: virtual
  number ranges, bursts of votes from one network, repeated patterns.
* **The widget and the service behind it.** A widget on an arbitrary website means the voting is
  hosted by Veriqa rather than by the integrator: allowed origins, rate limits, an abuse policy.
* **Email** does not fit this transaction: an address costs nothing, so a vote confirmed by email
  anchors nothing.

A voting or contest platform that accepts an external OpenID Connect provider can connect Veriqa
as its sign-in method today, like any other OIDC client — see
[SaaS builders](/docs/integrations/saas-builders) for how that connection works. Whether the platform
lets a public audience sign in through an external provider is up to that platform. The
platform then counts the votes itself, so the anchor and the one-tap confirmation are available
this way, while the receipt and the checkable total are not.

## Where its limits are

<Warning>
  A confirmed vote is **attributable**: it is tied to the voter's confirmation. This fits a fan
  favorite, a contest or an award. It does not fit elections or any decision with legal
  consequences, where the secrecy of the ballot matters.
</Warning>

* **Votes bought from real people are not stopped by anything here.** The phone anchor raises the
  price of a vote to the cost of a person's time and stops there.
* **The receipt shifts trust but does not remove it.** It proves that the website did not alter the
  result; it does not prove that Veriqa did not issue fictitious identities.
* **Coverage.** Where a large share of the audience uses none of the supported messengers — in the
  US, for example, no single messenger dominates — the widget cannot be the only way to vote, and
  any fallback without a phone anchor brings the guarantee down to its own level.
* **The receipt is an attestation of the count**, not an electronic signature in the legal sense.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.