Ontwikkelaar API

Overzicht

De ontwikkelaar API is een REST API onder /api/v1. Alle verzoeken en antwoorden zijn JSON. Het volledige, interactieve contract bevindt zich in de API referentie; deze pagina brengt u naar je eerste succesvolle gesprek.

Authenticatie

Authenticeer met een werkruimte API-sleutel verzonden als een Bearer-token. Genereer er een in Studio → Ontwikkelaar API (betaalde abonnementen). Het geheim wordt één keer getoond - bewaar het op een veilige plek; als je deze kwijtraakt, trekt u de sleutel in en maakt u een nieuwe aan.

Authorization: Bearer $POLLSLIVE_KEY

Sleutels hebben beheerdersbevoegdheid binnen hun werkruimte. Geef nooit een sleutel vrij in code aan de clientzijde: roep de API aan vanaf je server.

You can also authenticate using an OAuth 2.0 Client Credentials access token for machine-to-machine integrations.

Quickstart

Maak een poll, publiceer deze en lees vervolgens de resultaten:

curl -X POST https://pollslive.com/api/v1/polls \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lunch vote",
    "content": {
      "questions": [{
        "id": "q1", "kind": "multiple_choice", "text": "Where to?",
        "type": "single",
        "options": [
          { "id": "a", "label": "Tacos" },
          { "id": "b", "label": "Sushi" }
        ]
      }]
    }
  }'

curl -X PATCH https://pollslive.com/api/v1/polls/POLL_ID \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "publish": true }'

curl https://pollslive.com/api/v1/polls/POLL_ID/results \
  -H "Authorization: Bearer $POLLSLIVE_KEY"

Vraagtypes

Een poll is een stapel getypte dia's. Stel kind in op elke dia. Elk van deze soorten kan via de API worden geschreven:

• multiple_choice: type (enkel/meerdere), options[]. Stembaar asynchroon.
• quiz: options[], correctOptionIds[], timeLimitSec, points, speedBonus.
• quiz_typed: acceptedAnswers[], timeLimitSec, points, speedBonus (alleen livesessies; 1-10 geldige antwoorden van elk maximaal 60 tekens, vergeleken zonder op hoofdletters en extra spaties te letten; deelnemers typen maximaal 40 tekens).
• quiz_order: items[], timeLimitSec, points, speedBonus (alleen livesessies; 3-6 items met id en label, opgeslagen in de juiste volgorde; deelnemers zien ze geschud en alleen de exacte volgorde levert punten op).
• scale: min, max, minLabel, maxLabel, statements[].
• ranking: options[] (respondenten bestellen ze).
• open_ended: maxLength, render (lijst/wolk).
• qa: moderated, allowUpvotes.
• estimation: cards[], deckPreset (Planning Poker; alleen livesessies, stemmen blijven verborgen totdat je ze onthult).
• brainstorm: maxLength, moderated, groups[], votesPerPerson (alleen livesessies; de zaal stemt op de groepen die jij uit de ideeën maakt).
• content - alleen weergave.

{
  "questions": [
    {
      "id": "s1", "kind": "scale", "text": "How likely are you to recommend us?",
      "min": 0, "max": 10, "minLabel": "Not likely", "maxLabel": "Very likely"
    },
    {
      "id": "q2", "kind": "quiz", "text": "Capital of France?",
      "options": [{ "id": "a", "label": "Paris" }, { "id": "b", "label": "Rome" }],
      "correctOptionIds": ["a"], "timeLimitSec": 20, "points": 100, "speedBonus": true
    },
    {
      "id": "q3", "kind": "ranking", "text": "Rank these features by importance",
      "options": [
        { "id": "r1", "label": "Speed" },
        { "id": "r2", "label": "Reliability" },
        { "id": "r3", "label": "Price" }
      ]
    },
    {
      "id": "q4", "kind": "open_ended", "text": "Any other feedback?",
      "maxLength": 300, "render": "list"
    },
    {
      "id": "q5", "kind": "qa", "text": "Questions for the presenter",
      "moderated": true, "allowUpvotes": true
    }
  ]
}

Afbeeldingen, video & links

Elke dia en elke optie kan mediabevatten. Upload of geef een URL door aan POST /media en sluit het geretourneerde object in. Afbeeldingen worden gedownload, opnieuw gecodeerd naar WebP en opnieuw gehost (kleinere payloads). YouTube video's en weblinks behouden hun URL en renderen client-side, zodat u nooit hoeft te betalen om video te hosten. Je kunt ook passeren media: { type, url } inline op een dia/optie en de API lost het op wanneer u opslaat.

# 1) Ingest an image (returns { data: { type, url, storedUrl, width, height } })
curl -X POST https://pollslive.com/api/v1/media \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/cat.jpg" }'

# 2) Embed the storedUrl on a slide option
{ "id": "a", "label": "Option A", "media": { "type": "image", "url": "https://pollslive.com/media/abc.webp" } }

# Or pass the original URL inline - the API resolves it on save:
{ "id": "a", "label": "Option A", "media": { "type": "image", "url": "https://example.com/cat.jpg" } }

# YouTube on a question slide
{ "id": "q1", "kind": "content", "text": "Watch this first",
  "media": { "type": "youtube", "url": "https://youtu.be/dQw4w9WgXcQ" } }

Reacties & resultaten

multiple_choice Voor dia's wordt gestemd via POST /polls/{id}/votes. Elke andere soort neemt asynchrone antwoorden via POST /polls/{id}/responses - stuur het veld dat overeenkomt met de dia (scaleValue, rankingOrder, text, of optionIds). Aggregaten per dia lezen van GET /polls/{id}/results.

curl -X POST https://pollslive.com/api/v1/polls/POLL_ID/responses \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "voterId": "user-123", "slideId": "s1", "scaleValue": 9 }'

curl -X POST https://pollslive.com/api/v1/polls/POLL_ID/responses \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voterId": "user-123",
    "slideId": "q3",
    "rankingOrder": ["r2", "r1", "r3"]
  }'

curl -X POST https://pollslive.com/api/v1/polls/POLL_ID/responses \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "voterId": "user-123", "slideId": "q4", "text": "Great product!" }'

Livesessies en sessiebeheer

Met een livesessie kun je in realtime een poll uitvoeren voor een publiek. Creëer een sessie via de API, deel de PIN- of QR-code met je publiek en beheer vervolgens het tempo en de zichtbaarheid van de resultaten met het controle-eindpunt.

curl -X POST https://pollslive.com/api/v1/sessions \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pollId": "POLL_ID" }'
# Response includes: id, pin, status, currentSlideIndex, hostToken (once)

curl -X POST https://pollslive.com/api/v1/sessions/SESSION_ID/control \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "next" }'

Alle sessiebeheeracties

POST naar /api/v1/sessions/{id}/control (Bearer) met een van deze actietekenreeksen.

{ "action": "goto", "slideIndex": 2 }

Resultaten exporteren

Download de verzamelde enquêteresultaten als UTF-8 RFC-4180 CSV-bestand, of als PDF-rapport met ?format=pdf. Elke rij bevat het dianummer, de vraagtekst, het type, het antwoordlabel en het aantal of de waarde. Compatibel met Excel, Google Sheets en alle CSV-tools. Alleen betaalde abonnementen.

curl https://pollslive.com/api/v1/polls/POLL_ID/export \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  --output results.csv

# CSV structure:
# Slide, Question, Type, Answer / Label, Count / Value
# 1, "Where to?", multiple_choice, Tacos, 12
# 1, "Where to?", multiple_choice, Sushi, 8
# 2, "Rate your experience", scale, Average, 8.50
# 2, "Rate your experience", scale, Rating 10, 5

Eindpunten

• Peilingen: GET/POST /polls, GET/PATCH/DELETE /polls/{id}
• Resultaten: GET /polls/{id}/results, GET/POST /polls/{id}/responses
• Stemmen: GET/POST /polls/{id}/votes
• Media: POST /media
• Sessies: POST /sessions, GET /sessions/{id}, POST /sessions/{id}/control
• Exporteren: GET /polls/{id}/export

Bekijk aanvraag-/antwoordvormen en probeer live oproepen in de API referentie.

Fouten en snelheidslimieten

Fouten gebruiken een stabiele envelop:

{ "error": { "code": "not_found", "message": "Poll not found." } }

Algemene codes: 401 ongeldige/ontbrekende sleutel, 402 planupgrade vereist, 404 niet gevonden, 409 conflict (bijv. al gestemd, poll gesloten), 422 validatie mislukt, 429 tarief beperkt.

Snelheidslimieten

De API staat 120 verzoeken per minuut per sleutel toe voor alle endpoints. Media-opname (POST /media) is apart beperkt tot 30 verzoeken per minuut. Bij overschrijding van een limiet wordt HTTP 429 geretourneerd. Wacht even en probeer het opnieuw.

OAuth2 (Pro en hoger)

Elke betaalde workspace (Pro en hoger) kan OAuth2-clientreferenties gebruiken in plaats van statische sleutels. Maak clients aan in Studio; de OAuth-handleiding beschrijft de volledige flow.

Wijzigingen in de ontwikkelaars-API

Wijzigingen in de ontwikkelaars-API, nieuwste eerst. Productwijzigingen staan in het wijzigingslogboek.

API versiebeleid

De REST API heeft een versie op URL-niveau (/api/v1/). Belangrijke wijzigingen worden alleen geïntroduceerd met een nieuw versievoorvoegsel en een opzegtermijn van ten minste 90 dagen voor parallelle uitvoering. Additieve wijzigingen (nieuwe velden, nieuwe eindpunten, nieuwe webhook-gebeurtenissen) zijn niet-brekend en kunnen op elk moment worden verzonden.