Developers

Bouw op de ScoreStory API

ScoreStory heeft een publieke REST API. Alles wat je in de interface doet met onderzoeken, uitnodigingen, deelnemers, resultaten en mailings, kan ook via de API — vanuit je eigen koppeling, of vanuit een AI-agent die voor jou handelt. EU-gehost, op dezelfde endpoints als de app zelf.

API-referentie Interactieve documentatie voor elk endpoint. OpenAPI-schema De machineleesbare spec (OpenAPI 3, JSON).

Zo begin je

  1. Maak een token aan in de app, als admin, onder Organisatie → API-tokens. Geef het alleen de rechten die je koppeling nodig heeft, en liefst een einddatum.
  2. Roep GET /api/public-api/v1/me aan om te zien welke workspace, rechten en onderzoeksbeperking het token heeft.
  3. Doe je eerste aanroep:
# 1. Wat mag dit token?
curl -s https://app.scorestory.eu/api/public-api/v1/me \
  -H "Authorization: Bearer $SCORESTORY_TOKEN"

# 2. Onderzoek aanmaken (verplicht: name, metric_type, interview_locale)
#    metric_type: nps | enps | csat | ces | scale
curl -s -X POST https://app.scorestory.eu/api/surveys \
  -H "Authorization: Bearer $SCORESTORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Q3 pulse","metric_type":"nps","interview_locale":"nl"}'

# 3. Iemand uitnodigen
curl -s -X POST https://app.scorestory.eu/api/surveys/<survey_id>/invitations/personal \
  -H "Authorization: Bearer $SCORESTORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"recipient_email":"sam@example.com","recipient_name":"Sam"}'

Wat kan er

  • Onderzoeken aanmaken, lezen, wijzigen, klonen en verwijderen
  • Deelnemer-eigenschappen en thema's beheren
  • Persoonlijke uitnodigingen en gedeelde links aanmaken, opnieuw uitgeven, intrekken en per mail versturen
  • Deelnemers en hun transcripten lezen; een deelnemer wissen (AVG)
  • Resultaten lezen: overzicht, individuele scores, geschreven conclusie, thema's met quotes, trend over tijd
  • Mailings aanmaken, plannen, versturen, pauzeren en statistieken lezen

Spelregels

Rate limits gelden per token; een 429-antwoord heeft een Retry-After-header met het aantal seconden wachttijd. Foutmeldingen zien er altijd zo uit: {"error": {"code": "...", "message": "..."}} — branch op code, niet op de tekst. Versiebeheer is additief: velden worden alleen toegevoegd binnen een major versie, nooit verwijderd of hergebruikt. Er zijn nog geen webhooks — poll de resultaten-endpoints.

Voor AI-agents

Ben je een agent die voor iemand handelt, begin dan bij llms.txt — daar staat dezelfde informatie machineleesbaar. Je hebt sowieso een workspace-API-token nodig: dat kun je niet zelf aanmaken, dus vraag degene voor wie je werkt om er een aan te maken onder Organisatie → API-tokens en aan jou te geven.

Vragen

Mail ons op welcome@scorestory.eu.

Laatst bijgewerkt: 7 september 2026.