IAMMETER VOTING
PUBLIC REFERENCE / V1

Build voting into your website.

Use a shared voting page, embed an iframe, or create your own interface with the API.

https://vote.iammeter.com/api/v1
JSON requestsBearer credentials5-minute voting tokensOpenAPI 3.1

This documentation is public. Reading it does not grant access to polls, applications, accounts, or administrative actions. All examples use placeholders and perform no requests from this page.

Which credential belongs where?

ValueWhere it belongsWhat it does
Application, poll and option IDsBrowser or backendPublic identifiers. They do not grant management access.
Anonymous visitor UUIDBrowser localStorageA best-effort visitor label, not proof of identity.
Voting tokenBrowser memoryBearer credential for one poll and voter. Expires after 5 minutes.
Application API keyHost backend onlyScopes control poll management and verified identity exchange.

Use Authorization: Bearer TOKEN for application and voting credentials. They are different credential types. The application API key is a single opaque secret, not a Key + Secret request-signing pair.

SHARED PUBLIC PAGE

Anonymous voting, step by step

Enable link sharing for a published anonymous or mixed-mode poll in Details and results → Public sharing. This flow does not need an application ID or application API key. Replace every placeholder before making requests.

  1. Read the poll

    Get the title, options, selection limits, schedule and result policy. A disabled sharing link returns 404.

    curl 'https://vote.iammeter.com/api/v1/public/polls/YOUR_POLL_ID'
  2. Reuse a browser visitor ID

    Generate a visitor UUID once and retain it. Storage may be unavailable, in which case identity lasts only for the current page.

    // Use HTTPS in production. Keep this visitor ID for subsequent visits.
    const storageKey = "my-site:voting:visitor";
    let visitorId = localStorage.getItem(storageKey);
    if (!visitorId) {
      visitorId = crypto.randomUUID();
      localStorage.setItem(storageKey, visitorId);
    }
    // Send visitorId when requesting an anonymous voting credential.
    // Keep the returned token in memory, not localStorage.
  3. Request a voting token

    The UUID below is an example. Send the visitor ID retained by your browser.

    curl -X POST 'https://vote.iammeter.com/api/v1/public/polls/YOUR_POLL_ID/credentials' \
      -H 'Content-Type: application/json' \
      -d '{"visitor_id":"11111111-1111-4111-8111-111111111111"}'

    Example response:

    {
      "token": "YOUR_SHORT_LIVED_VOTING_TOKEN",
      "expires_at": "2026-12-01T12:05:00.000Z",
      "has_voted": false
    }

    If has_voted is true, show the recorded state. Refreshing a token does not reset the existing vote.

  4. Submit selected option IDs

    Generate a new request UUID for a new submission. Reuse that same key and selection when retrying the same request.

    curl -X POST 'https://vote.iammeter.com/api/v1/public/polls/YOUR_POLL_ID/ballots' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer YOUR_SHORT_LIVED_VOTING_TOKEN' \
      -H 'Idempotency-Key: YOUR_REQUEST_UUID' \
      -d '{"option_ids":["YOUR_OPTION_ID"]}'
  5. Load the allowed results

    Include the voting token for an after-vote result policy. If results are not open yet, show the appropriate message.

    curl 'https://vote.iammeter.com/api/v1/public/polls/YOUR_POLL_ID/results' \
      -H 'Authorization: Bearer YOUR_SHORT_LIVED_VOTING_TOKEN'

Draw your own anonymous voting interface

For a registered host website such as www or Contributor Center, register its exact origin or a domain rule and grant the application access to the poll. No host backend is needed for anonymous voting.

An allowed website rule of iammeter.com covers https://iammeter.com and all HTTPS subdomains, including www and Contributor, on the default port. An exact rule such as https://www.iammeter.com allows only that origin. Requests always send their actual exact parent_origin; never send a domain rule as the parent origin.

Read GET /embed/polls/{id}?application_id=YOUR_APPLICATION_ID, then call POST /credentials/anonymous?application_id=YOUR_APPLICATION_ID with:

{
  "application_id": "YOUR_APPLICATION_ID",
  "poll_id": "YOUR_POLL_ID",
  "parent_origin": "https://your-website.example",
  "visitor_id": "11111111-1111-4111-8111-111111111111"
}

Use the returned token with /polls/{id}/me, /polls/{id}/ballots, and /polls/{id}/results. Add ?application_id=YOUR_APPLICATION_ID to every cross-origin browser request, including credential requests, so CORS can check the registered host origin.

The /public/polls flow is the first-party shared-page entry point. For a different website origin, use the registered application flow above. Do not put an application API key in browser code.

Alternatively, embed https://vote.iammeter.com/embed?poll_id=YOUR_POLL_ID&application_id=YOUR_APPLICATION_ID and load the SDK from https://vote.iammeter.com/voting-sdk.js.

Vote as a signed-in host user

The host backend verifies its own login session and reads a stable user ID from that verified session. It exchanges the identity for a short-lived voting token using an application key with identity:exchange scope.

curl -X POST 'https://vote.iammeter.com/api/v1/credentials/exchange' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_APPLICATION_API_KEY' \
  -d '{
    "poll_id":"YOUR_POLL_ID",
    "subject":"VERIFIED_STABLE_USER_ID",
    "parent_origin":"https://your-website.example"
  }'

Return only the short-lived token to the browser. Never trust a user ID copied directly from an unverified browser request. An application can declare only its configured identity domains; specify identity_domain_id if the application has more than one.

Applications sharing the IAMMETER identity domain and the same stable user ID deduplicate votes across websites. Independent user systems use separate identity domains. Sharing an identity domain is an explicit backend trust decision.

Identity, duplicate votes and retries

The database permits one ballot per poll and internal voter. Anonymous identity is derived from the application namespace and visitor UUID. Anonymous visitors from different applications or websites are not automatically linked.

visitor_id identifies the anonymous visitor. Idempotency-Key identifies one submission attempt. Exact retries with the same key and payload for the same poll and voter return the original receipt, including with a fresh token (200, replayed: true); a first successful submission returns 201. A new initial-submission operation for an already-voted identity returns 409 already_voted; changing an existing ballot uses PUT instead.

After expiry, request a token with the same visitor ID and check has_voted before deciding whether another submit is needed. Ballots can be changed only when explicitly enabled; withdrawal is not supported.

Anonymous voting is not verified one-person-one-vote

Visitors can change UUIDs, clear storage, use another browser or script the public API. Token issuance is public and does not prove that the applicant is human. Rate limits slow requests; origin checks and CORS do not stop non-browser clients from simulating requests. There is no CAPTCHA, device fingerprinting or bot challenge in the current version.

CUSTOM FRONTEND INTEGRATION

Click-to-vote and changing a vote

Use this protocol for two selectable cards that save immediately without a separate submit button. One ballot per voter is retained: switching from A to B replaces that ballot’s choices and leaves the total voter count unchanged. The API supports both anonymous and verified identities; existing hosted widgets retain their current submit-once presentation.

1. Enable changes on the backend

Include allow_vote_changes: true when creating the poll. The default is false, including all existing polls after upgrade. The owning application can enable or disable changes on an existing draft or published poll with its backend-only polls:write key:

curl -X POST 'https://vote.iammeter.com/api/v1/polls/YOUR_POLL_ID/vote-change-policy' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_APPLICATION_API_KEY' \
  -d '{"allow_vote_changes":true}'

Shared display/vote grants do not allow another application to change this policy. Closed or archived polls cannot change it. An authorized administrator can configure polls created in the admin console through the protected admin API.

2. Restore the voter’s current selection

Keep the same visitor UUID. Obtain an anonymous voting token, then call GET /polls/{id}/me?application_id=YOUR_APPLICATION_ID with that token. Example:

{
  "has_voted": true,
  "allow_vote_changes": true,
  "can_change_vote": true,
  "ballot": {
    "id": "YOUR_BALLOT_ID",
    "version": 1,
    "option_ids": [
      "YOUR_OPTION_A_ID"
    ],
    "updated_at": "2026-12-01T12:00:00.000Z"
  }
}

Before the first vote, ballot is null and can_change_vote is false. That does not prevent the first vote. For an existing ballot, restore ballot.option_ids and retain ballot.version.

3. Submit or replace on selection

  • No ballot yet: POST /polls/{id}/ballots with option_ids. Success is 201, version 1.
  • Already voted and can_change_vote is true: PUT /polls/{id}/ballot with the complete new option_ids set and expected_version. Success is 200 with the same ballot ID and the next version.
  • Clicking the currently selected option: do not send another operation. Each accepted new PUT increments the version, even if its choices are identical.
curl -X PUT 'https://vote.iammeter.com/api/v1/polls/YOUR_POLL_ID/ballot?application_id=YOUR_APPLICATION_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_FRESH_VOTING_TOKEN' \
  -H 'Idempotency-Key: NEW_OPERATION_UUID' \
  -d '{"option_ids":["YOUR_OPTION_B_ID"],"expected_version":1}'

Every new successful write consumes its voting token. Obtain a fresh token using the same visitor UUID before each new submit/change. A token may still read state and results after consumption until it expires. Never place an application API key in browser code.

For standalone public sharing, use /public/polls/{id}/me, /public/polls/{id}/ballots and /public/polls/{id}/ballot; obtain tokens from the matching public credentials endpoint. No application_id is needed there. Do not mix public-link tokens and website integration contexts.

4. Keep the final click and server state consistent

  1. Debounce rapid clicks and serialize writes. While saving, retain only the newest pending selection; send it after the current request completes using the new version and a fresh token.
  2. Generate a new Idempotency-Key per intended operation. On network uncertainty, retry the exact same method, key and body; renew an expired token for the same voter if needed. A changed payload or a different operation type needs a new key.
  3. A replay returns the historical receipt’s version and option_ids, which may be older than the current ballot. It never reapplies an old selection. After an uncertain response, replay, or 409 ballot_version_conflict, read /me to recover current state before deciding whether to submit the latest intent as a new operation.
  4. Show saving/error status. On failure, restore the last confirmed selection and explain the error. After poll closure, its end time, permission revocation or can_change_vote: false, do not keep attempting changes.

403 vote_changes_not_allowed means the poll has not enabled changes. 409 credential_already_consumed requires a fresh voting token. 409 ballot_not_found means this identity has no ballot yet; 409 idempotency_conflict means a key was reused with a different operation or body. Validation failures and version conflicts leave an unused token unconsumed. Bodies must contain at least one option, meet the poll’s selection limits and reference options belonging to this poll. Multi-select PUT replaces the whole set; it does not append choices.

Changes preserve after-vote result access. They are blocked outside the voting window and respect current application, grant, origin and public-link controls. The same anonymous identity limitations apply: clearing storage or using another application’s anonymous namespace does not recover the original ballot.

Result policies and limits

PolicyWhen results are returned
publicWhen the poll is published or closed and the entry point is authorized.
after_voteA valid matching voting credential must identify a voter with a recorded ballot.
after_closeAfter explicit closure or the configured end time.
privateOnly an authorized administrative reader can view aggregates.
  • Global API limit: 300 requests per source IP per minute.
  • Anonymous credential issuance: 30 requests per source IP per minute for each issuance route.
  • Limits are currently stored in one API process and reset on restart. They are request limits, not one vote per IP.
  • Request bodies: up to 64 KiB. Polls: 2–20 options. The server validates option ownership, selection count and the voting window.

Multiple-choice percentages use the number of voters as the denominator, so totals may exceed 100%. Disabling public sharing invalidates its tokens and leaves already-recorded ballots and website grants intact.

ENDPOINT REFERENCE

Public sharing API

First-party shared voting pages. Link sharing must be enabled. Voting tokens remain required for submission and personal state.

GET/public/polls/{id}Public; poll permissions apply

Standalone sharing: Authorized published poll metadata; never includes counts

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

GET/public/polls/{id}/meShort-lived voting token

Read this voter’s current ballot, selected option IDs, version and change permission

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

POST/public/polls/{id}/ballotsShort-lived voting token

Cast the first ballot (201); exact operation retries return the original receipt (200)

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}
Idempotency-KeyheaderYes{"type":"string","minLength":8,"maxLength":128}

Request body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "option_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          }
        },
        "required": [
          "option_ids"
        ]
      }
    }
  }
}

Responses

200 · 201 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

GET/public/polls/{id}/resultsDepends on result policy

Standalone sharing: Grant and policy controlled results; after_vote requires matching application voter credential

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

POST/public/polls/{id}/credentialsPublic; poll permissions apply

Public sharing anonymous credential

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}

Request body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "visitor_id"
        ],
        "properties": {
          "visitor_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      }
    }
  }
}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

PUT/public/polls/{id}/ballotShort-lived voting token

Replace this voter’s ballot choices, with optimistic version checking

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}
Idempotency-KeyheaderYes{"type":"string","minLength":8,"maxLength":128}

Request body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "option_ids",
          "expected_version"
        ],
        "properties": {
          "option_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "expected_version": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483646,
            "description": "Version from GET /me or the last successful write. Refresh /me after a 409 conflict."
          }
        }
      }
    }
  }
}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

ENDPOINT REFERENCE

Website integration API

Registered host websites. Poll grants, registered origins, identity modes and result policies are enforced for every request.

GET/healthPublic; poll permissions apply

Database readiness

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

GET/embed/polls/{id}Public; poll permissions apply

Authorized published poll metadata; never includes counts

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}
application_idqueryYes{"type":"string","format":"uuid"}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

POST/credentials/anonymousPublic; poll permissions apply

Best-effort anonymous visitor credential

Request body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "poll_id": {
            "type": "string",
            "format": "uuid"
          },
          "application_id": {
            "type": "string",
            "format": "uuid"
          },
          "parent_origin": {
            "type": "string"
          },
          "visitor_id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "poll_id",
          "application_id",
          "parent_origin",
          "visitor_id"
        ]
      }
    }
  }
}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

GET/polls/{id}/meShort-lived voting token

Read this voter’s current ballot, selected option IDs, version and change permission

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

POST/polls/{id}/ballotsShort-lived voting token

Cast the first ballot (201); exact operation retries return the original receipt (200)

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}
Idempotency-KeyheaderYes{"type":"string","minLength":8,"maxLength":128}

Request body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "option_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          }
        },
        "required": [
          "option_ids"
        ]
      }
    }
  }
}

Responses

200 · 201 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

GET/polls/{id}/resultsDepends on result policy

Grant and policy controlled results; after_vote requires matching application voter credential

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}
application_idqueryYes{"type":"string","format":"uuid"}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

PUT/polls/{id}/ballotShort-lived voting token

Replace this voter’s ballot choices, with optimistic version checking

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}
Idempotency-KeyheaderYes{"type":"string","minLength":8,"maxLength":128}

Request body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": [
          "option_ids",
          "expected_version"
        ],
        "properties": {
          "option_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "expected_version": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483646,
            "description": "Version from GET /me or the last successful write. Refresh /me after a 409 conflict."
          }
        }
      }
    }
  }
}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

ENDPOINT REFERENCE

Host backend API

Application API key required. Scopes are identity:exchange, polls:read or polls:write; shared display access does not grant ownership or editing rights.

POST/credentials/exchangeServer API key

Trusted host identity exchange; scope identity:exchange

Request body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "poll_id": {
            "type": "string",
            "format": "uuid"
          },
          "subject": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "parent_origin": {
            "type": "string"
          },
          "identity_domain_id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "poll_id",
          "subject",
          "parent_origin"
        ]
      }
    }
  }
}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

POST/pollsServer API key

Create owned draft; scope polls:write

Request body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PollInput"
      }
    }
  }
}

Responses

201 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

GET/pollsServer API key

Find this application resource links; scope polls:read

Parameters

NameLocationRequiredSchema
resource_typequeryYes{"type":"string"}
resource_idqueryYes{"type":"string"}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

POST/polls/{id}/publishServer API key

publish own application poll; scope polls:write

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

POST/polls/{id}/closeServer API key

close own application poll; scope polls:write

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}

Responses

200 · 401 · 403 · 409 · 422 · 429. See the OpenAPI file for response schemas and shared definitions.

POST/polls/{id}/vote-change-policyServer API key

Enable or disable vote changes without changing poll content

Parameters

NameLocationRequiredSchema
idpathYes{"type":"string","format":"uuid"}

Request body

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/VoteChangePolicy"
      }
    }
  }
}

Responses

200 · 401 · 403 · 409 · 422. See the OpenAPI file for response schemas and shared definitions.

Error handling

{
  "error": "already_voted"
}
StatusTypical meaning
401Missing, invalid or expired credentials.
403Insufficient permission, unapproved origin, or hidden results.
404Unavailable poll, disabled share link, or unknown resource.
409Already voted, consumed credential, closed poll, or conflicting state.
422Invalid fields, options, selection count or identity mode.
429Rate limited. Check the status before parsing; this response may be text.

Most errors are JSON with error, optional validation issues, and an optional request_id. Keep credentials out of URLs, analytics and logs.