REST-API
Askalot stellt eine REST-API für den programmatischen Zugriff auf alle Funktionen der Plattform bereit. Mit der API automatisieren Sie Umfrage-Workflows, binden externe Systeme an und bauen eigene Anwendungen auf der Askalot-Plattform auf.
Erste Schritte
Abschnitt betitelt „Erste Schritte“Basis-URL
Abschnitt betitelt „Basis-URL“https://portor.<tenant>.askalot.io/api/v1Ersetzen Sie <tenant> durch den Tenant-Namen Ihrer Organisation (z. B. portor.acme.askalot.io).
Authentifizierung
Abschnitt betitelt „Authentifizierung“Jede API-Anfrage muss mit einem persönlichen API-Token authentifiziert werden.
Ein Token erzeugen:
- Melden Sie sich bei
https://roundtable.<tenant>.askalot.ioan - Öffnen Sie die Profileinstellungen
- Scrollen Sie zum Abschnitt „API-Tokens“
- Klicken Sie auf „Neues Token erzeugen“
- Kopieren Sie das Token (es wird nur einmal angezeigt)
Das Token verwenden:
Senden Sie Ihr Token im Header X-Api-Token:
curl -H "X-Api-Token: your_token_here" \ https://portor.<tenant>.askalot.io/api/v1/projectsEigenschaften des Tokens:
- Format: Tokens beginnen mit
aslat_(aslat_<32 characters>); an diesem Präfix erkennen Secret-Scanner einen versehentlichen Commit. Auf dem Server wird zur Identifizierung nur das Präfix gespeichert – das vollständige Token wird einmal beim Erzeugen angezeigt und danach nie wieder. - Header: Senden Sie es im Header
X-Api-Token. Das ist der Weg für REST-Zugangsdaten; der HeaderAuthorization: Bearerist bei Portor für OAuth-Access-Tokens reserviert (die eine MCP-Sitzung mitführt und die auch REST akzeptiert), nicht für API-Tokens. - Geltungsbereich: authentifiziert nur die REST-API und wird von der MCP-Schnittstelle nicht akzeptiert. Ein Token gehört zu der Organisation, in der Sie beim Erzeugen gearbeitet haben: Jede Anfrage damit handelt in dieser Organisation, mit den Rollen, die Sie dort haben – eine Rolle in einer anderen Organisation gilt nicht. Um über REST in einer anderen Organisation zu arbeiten, wechseln Sie im Browser zu ihr und erzeugen dort ein Token. Entfernt ein Administrator Sie aus dieser Organisation, werden ihre Tokens zusammen mit der Mitgliedschaft widerrufen.
- Widerruf: jederzeit in den Profileinstellungen möglich; der Widerruf wirkt sofort.
Laufzeit und Rotation von Tokens
Abschnitt betitelt „Laufzeit und Rotation von Tokens“Beim Erzeugen eines Tokens wählen Sie eine Laufzeit – die Auswahlliste in den Profileinstellungen bietet 30 Tage, 90 Tage (der Standard) oder 1 Jahr. Eine Laufzeit ist Pflicht; für neue Tokens gibt es keine Option „läuft nie ab“ (nur ältere Tokens aus der Zeit davor haben möglicherweise kein Ablaufdatum).
- Die Profileinstellungen zeigen für jedes Token das Ablaufdatum und die verbleibenden Tage und markieren ein Token zur Rotation, sobald es innerhalb von 14 Tagen abläuft.
- So rotieren Sie: Erzeugen Sie ein Ersatz-Token, stellen Sie Ihre Integration darauf um und widerrufen Sie dann das alte. Tokens verlängern sich nicht automatisch – ein abgelaufenes Token liefert
401und muss ersetzt werden.
Interaktive Dokumentation
Abschnitt betitelt „Interaktive Dokumentation“Erkunden Sie die API interaktiv mit Swagger UI unter:
https://portor.<tenant>.askalot.io/api/v1/docsIn der interaktiven Dokumentation können Sie:
- alle verfügbaren Endpunkte durchsehen
- Anfrage- und Antwortschemas ansehen
- API-Aufrufe direkt im Browser testen
Zentrale Ressourcen
Abschnitt betitelt „Zentrale Ressourcen“Projekte
Abschnitt betitelt „Projekte“Projekte sind die obersten Container, in denen Sie Ihre Umfrageforschung organisieren.
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/api/v1/projects |
Alle Projekte auflisten |
POST |
/api/v1/projects |
Ein neues Projekt anlegen |
GET |
/api/v1/projects/{id} |
Projekt über die ID abrufen |
PUT |
/api/v1/projects/{id} |
Ein Projekt ändern |
DELETE |
/api/v1/projects/{id} |
Ein Projekt löschen |
POST |
/api/v1/projects/{id}/owners |
Projekteigentümer hinzufügen |
DELETE |
/api/v1/projects/{id}/owners |
Projekteigentümer entfernen |
Beispiel: Ein Projekt anlegen
curl -X POST https://portor.<tenant>.askalot.io/api/v1/projects \ -H "X-Api-Token: your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Customer Satisfaction Study", "description": "Q1 2026 customer feedback survey" }'Antwort:
{ "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Customer Satisfaction Study", "description": "Q1 2026 customer feedback survey", "created_at": "2026-01-02T10:30:00Z", "questionnaire_ids": [], "campaign_ids": []}Fragebögen
Abschnitt betitelt „Fragebögen“Fragebögen legen die Struktur einer Umfrage in QML (Questionnaire Markup Language) fest.
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/api/v1/questionnaires |
Alle Fragebögen auflisten |
POST |
/api/v1/questionnaires |
Einen neuen Fragebogen anlegen |
GET |
/api/v1/questionnaires/{id} |
Fragebogen über die ID abrufen |
PUT |
/api/v1/questionnaires/{id} |
Einen Fragebogen ändern |
DELETE |
/api/v1/questionnaires/{id} |
Einen Fragebogen löschen |
GET |
/api/v1/questionnaires/{id}/versions/{version_id}/translations |
Die Übersetzungen einer Version je Sprache auflisten (vollständig, unübersetzte Schlüssel, eingefroren, von Hand bearbeitet) |
GET |
/api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} |
Die Übersetzung in eine Sprache samt Quelltexten abrufen |
PUT |
/api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} |
Übersetzten Text speichern (texts, base_updated_at); teilweise, über das Gespeicherte zusammengeführt |
DELETE |
/api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} |
Die Übersetzung in eine Sprache löschen (abgelehnt, sobald eingefroren) |
Abfrageparameter:
project_id– nach Projekt filternstatus– nach Status filtern (draft,active,paused,completed)
Kampagnen
Abschnitt betitelt „Kampagnen“Kampagnen verbinden Fragebögen mit Befragten, um Daten zu erheben.
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/api/v1/campaigns |
Alle Kampagnen auflisten |
POST |
/api/v1/campaigns |
Eine neue Kampagne anlegen |
GET |
/api/v1/campaigns/{id} |
Kampagne über die ID abrufen |
PUT |
/api/v1/campaigns/{id} |
Eine Kampagne ändern |
DELETE |
/api/v1/campaigns/{id} |
Eine Kampagne löschen |
PUT |
/api/v1/campaigns/{id}/pool |
Der Kampagne einen Befragtenpool zuweisen |
GET |
/api/v1/campaigns/{id}/pool |
Den zugewiesenen Pool der Kampagne abrufen |
PUT |
/api/v1/campaigns/{id}/questionnaire |
Den Fragebogen der Kampagne ändern |
POST |
/api/v1/campaigns/{id}/interviewers |
Der Kampagne Interviewer hinzufügen |
DELETE |
/api/v1/campaigns/{id}/interviewers |
Interviewer aus der Kampagne entfernen |
Abfrageparameter:
project_id– nach Projekt filternquestionnaire_id– nach Fragebogen filternstatus– nach Status filternexpand=true– verknüpfte Objekte einbeziehen (Projekt, Fragebogen, Befragte)
Eine Kampagne anlegen: POST /api/v1/campaigns erfordert name, project_id, questionnaire_id und offers_ai_channel. offers_ai_channel (Boolean) gibt an, ob Befragte die Umfrage auch in ihrem eigenen KI-Assistenten beantworten dürfen. Es hat keinen Standardwert, und eine Anfrage ohne diesen Wert wird abgelehnt. Ist er true, sind zusätzlich intro_text und consent_text erforderlich. Siehe KI-gestütztes Selbstinterview.
Kampagnenmodi:
Askalot unterstützt zwei Kampagnenmodi:
- Direktmodus: Befragte füllen Umfragen selbstständig über individuelle Links aus
- Interviewergestützter Modus: Interviewer führen die Umfragen telefonisch oder persönlich mit den Befragten durch
Der Modus ergibt sich automatisch daraus, ob der Kampagne Interviewer zugewiesen sind.
Jede Umfrage hält außerdem ihren eigenen Modus (direct, ai_assisted oder field_interview) im Feld mode fest. Eine Umfrage ist ai_assisted, wenn die Kampagne den KI-Assistenten anbietet und die befragte Person dort vor dem Antworten eingewilligt hat.
Befragte
Abschnitt betitelt „Befragte“Befragte sind die Zielpersonen der Umfragen – die Menschen, die befragt werden.
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/api/v1/respondents |
Alle Befragten auflisten |
POST |
/api/v1/respondents |
Eine neue befragte Person anlegen |
GET |
/api/v1/respondents/{id} |
Befragte Person über die ID abrufen |
PUT |
/api/v1/respondents/{id} |
Eine befragte Person ändern |
DELETE |
/api/v1/respondents/{id} |
Eine befragte Person löschen |
Abfrageparameter:
source_system– nach Quelle filtern (z. B.crm,panel_provider)campaign_id– nach Kampagne filtern
Hinweis: Interviewer sind Benutzer mit der Rolle interviewer. Sie werden über den Endpunkt /api/v1/users verwaltet.
Beispiel: Eine befragte Person importieren
curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondents \ -H "X-Api-Token: your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Jane Smith", "email": "[email protected]", "age": 35, "gender": "female", "location": "New York", "external_id": "CRM-12345", "source_system": "salesforce", "custom_attributes": {"state": "NY", "zip_code": "10001"} }'Demografische Felder:
Zu Befragten lassen sich demografische Daten für Zielgruppenauswahl und Analyse hinterlegen:
age– Alter der befragten Persongender– Geschlechtsidentitätlocation– geografischer Ort (Freitext, typischerweise"City, Country")external_id– die Kennung in Ihrem Systemsource_system– Herkunft der Befragtendatenpreferred_language– optionale bevorzugte Sprache (en,es,fr,de,hu), verwendet für die Einladung und als vorausgewählte Sprache der Umfrage, wenn die Kampagne sie anbietet
Feinere geografische Angaben als location – Straße, Stadt, Bundesland, Postleitzahl, Land als getrennte Werte – gehören in custom_attributes und sind als custom_attributes.<key> überall ansprechbar, wo sich ein Attribut einer befragten Person nennen lässt (Stichprobenfaktoren, Zuordnungen externer Eingaben). Ein Kalibrierungsziel nennt die Datensatzspalte, in die das Attribut extrahiert wurde, _custom_<key>. Zusätzliche Schlüssel auf oberster Ebene werden ignoriert statt gespeichert; ein CRM-Export, der city als eigenes Feld sendet, verliert diesen Wert also stillschweigend.
Umfragen
Abschnitt betitelt „Umfragen“Umfragen erfassen einzelne Umfragesitzungen und ihre Antworten.
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/api/v1/surveys |
Alle Umfragen auflisten |
POST |
/api/v1/surveys |
Eine neue Umfragesitzung anlegen |
GET |
/api/v1/surveys/{id} |
Umfrage über die ID abrufen |
PUT |
/api/v1/surveys/{id} |
Den Status einer Umfrage ändern |
DELETE |
/api/v1/surveys/{id} |
Eine Umfrage löschen |
GET |
/api/v1/surveys/{id}/current-step |
Aktuelle Frage + Optionen + Status (Darstellungsformat von Umfragen) |
POST |
/api/v1/surveys/{id}/responses |
Eine Antwort übermitteln; der nächste Schritt ist in die Antwort eingebettet |
POST |
/api/v1/surveys/{id}/finish |
Die Umfrage ausdrücklich abschließen (idempotent) |
Abfrageparameter:
questionnaire_id– nach Fragebogen filterncampaign_id– nach Kampagne filternrespondent_id– nach befragter Person filternstatus– nach Status filtern (pending,in_progress,completed)expand=true– verknüpfte Objekte einbeziehen
API-Antworten zu Umfragen enthalten status sowie einen abgeleiteten, schreibgeschützten Boolean completed (true genau dann, wenn status gleich completed ist). Der Abschluss wird über eine Änderung von status ausgedrückt – es gibt weder eine Eingabe noch einen Filterparameter completed.
Das Beantworten einer Umfrage über POST /api/v1/surveys/{id}/responses ist auf Tests und Simulation beschränkt: Eine Umfrage, zu der eine Einladung versendet wurde, wird abgelehnt, sodass sich keine Antworten programmatisch in ein laufendes Feldinterview schreiben lassen. Auf diesem Weg übermittelte Antworten werden als maschinell erzeugt erfasst, und ihre Antwortzeiten werden von der Speeder-Erkennung ausgenommen.
Befragtenpools
Abschnitt betitelt „Befragtenpools“Befragtenpools ordnen Befragte in wiederverwendbaren Gruppen für Kampagnen.
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/api/v1/respondent-pools |
Alle Befragtenpools auflisten |
POST |
/api/v1/respondent-pools |
Einen neuen Pool anlegen |
GET |
/api/v1/respondent-pools/{id} |
Pool über die ID abrufen |
DELETE |
/api/v1/respondent-pools/{id} |
Einen Pool löschen |
POST |
/api/v1/respondent-pools/{id}/respondents |
Befragte zum Pool hinzufügen |
DELETE |
/api/v1/respondent-pools/{id}/respondents |
Befragte aus dem Pool entfernen |
POST |
/api/v1/respondent-pools/generate |
Einen Pool aus einer Stichprobenstrategie ziehen (requested_size erforderlich); der Pool speichert seine Ziehungseinstellungen |
POST |
/api/v1/respondent-pools/preview |
Eine Ziehung in der Vorschau ansehen, ohne einen Pool anzulegen |
POST |
/api/v1/respondent-pools/{id}/refresh |
Einen Strategie-Pool mit seinen eigenen gespeicherten Ziehungseinstellungen neu ziehen |
Abfrageparameter:
project_id– nach Projekt filtern
Stichprobenstrategien
Abschnitt betitelt „Stichprobenstrategien“Stichprobenstrategien legen demografische Zielverteilungen fest, um repräsentative Stichproben zu bilden, und bestimmen, wie die Übereinstimmung damit bewertet wird. Eine Strategie enthält keine Größen- oder Auswahleinstellungen: Das sind Eingaben für POST /api/v1/respondent-pools/generate und werden im angelegten Pool gespeichert.
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/api/v1/sampling-strategies |
Alle Strategien auflisten |
POST |
/api/v1/sampling-strategies |
Eine neue Strategie anlegen |
GET |
/api/v1/sampling-strategies/{id} |
Strategie über die ID abrufen |
PUT |
/api/v1/sampling-strategies/{id} |
Eine Strategie ändern |
DELETE |
/api/v1/sampling-strategies/{id} |
Eine Strategie löschen |
Abfrageparameter:
project_id– nach Projekt filtern
Beispiel: Eine Stichprobenstrategie anlegen
curl -X POST https://portor.<tenant>.askalot.io/api/v1/sampling-strategies \ -H "X-Api-Token: your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Representative Sample", "project_id": "550e8400-e29b-41d4-a716-446655440000", "factors": [ { "name": "Gender", "attribute_path": "gender", "target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02} }, { "name": "Age Group", "attribute_path": "age", "factor_type": "bucketed", "target_distribution": {"18-34": 0.35, "35-54": 0.40, "55+": 0.25} } ] }'Beispiel: Einen Pool aus der Strategie ziehen
curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondent-pools/generate \ -H "X-Api-Token: your_token" \ -H "Content-Type: application/json" \ -d '{ "strategy_id": "<strategy id>", "pool_name": "Pilot wave", "requested_size": 100, "oversample_factor": 1.2 }'requested_size ist erforderlich; oversample_factor (Standard 1.0), selection_algorithm (greedy oder random_constrained, Standard greedy), require_email (Standard false) und exclude_respondent_ids (standardmäßig keine) sind optional. Ziehen Sie aus derselben Strategie jederzeit einen zweiten Pool in anderer Größe, wenn Sie einen brauchen.
Bundles
Abschnitt betitelt „Bundles“Ein Bundle bindet ein Projekt → einen Fragebogen → eine ausgewählte Teilmenge von Kampagnen an eine einzige lineare Datensatzkette Bronze → Silver → Gold – die Einheit, nach der das Pipeline-Board von Balansor gegliedert ist.
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/api/v1/bundles |
Alle Bundles auflisten |
POST |
/api/v1/bundles |
Ein neues Bundle anlegen |
GET |
/api/v1/bundles/{id} |
Bundle-Details, einschließlich der Konfigurationen seiner Stufen (Silver-Kalibrierungsziele, Gold-Operationen) |
DELETE |
/api/v1/bundles/{id} |
Ein Bundle löschen (samt seiner Datensatzkette) |
POST |
/api/v1/bundles/{id}/clone |
Ein Bundle klonen – tiefe Kopie: fertige Datensätze und Stufenkonfigurationen werden übernommen |
GET |
/api/v1/bundles/{id}/quality |
Die Repräsentativitätsübersicht des Bundles (Auswahl, Feldphase, gewichtet, Verschiebung in der Feldphase, Rücklauf) |
GET |
/api/v1/bundles/{id}/comparison |
Vergleich Bronze gegen Silver (409 conflict, bis beide Stufen ready sind) |
GET |
/api/v1/bundles/{id}/coding |
Stand der Codierung offener Antworten – die Codierungskandidaten, die das Bronze anbietet, die Fragenauswahl des Analysten und je Frage die vorgeschlagenen Dimensionen mit ihren Kategorien und ihrem Auswahlstatus (welche Dimensionen zu Spalten werden, entscheiden Sie weiterhin in der Balansor-Oberfläche) |
PUT |
/api/v1/bundles/{id}/coding/selection |
Festlegen, welche Freitext-Einheiten dieses Bundle codiert – vollständige Ersatzmenge der Einheitenschlüssel (Manager-Rolle, identifizierter Benutzer erforderlich) |
POST |
/api/v1/bundles/{id}/strategy |
Die aktuelle Stichprobenstrategie des Bundles zuweisen oder entfernen (Manager-Rolle, identifizierter Benutzer erforderlich) |
PUT |
/api/v1/bundles/{id}/targets |
Die Kalibrierungsziele des Bundles bearbeiten – die Gewichtungsspezifikation für Silver, jedes Ziel raked oder benchmark (Manager-Rolle, identifizierter Benutzer erforderlich) |
GET |
/api/v1/bundles/{id}/targets/copy-preview?source_bundle_id={source} |
Vorschau auf das Kopieren der Kalibrierungsziele eines anderen Bundles in dieses: addable und rejected mit Begründungen; schreibt nichts (Manager-Rolle) |
Abfrageparameter:
project_id– nach Projekt filtern
Die Stufenoperationen (Extraktion, Codierung + Gewichtung, Verfeinerung, Export) laufen über die MCP-Tools für Bundles und Datensätze – die vollständige Referenz der Qualitäts- und Stufenparameter finden Sie unter mcp-bundle-tools.md und mcp-dataset-tools.md.
Antwortformat
Abschnitt betitelt „Antwortformat“Erfolgreiche Antworten
Abschnitt betitelt „Erfolgreiche Antworten“Alle erfolgreichen Antworten liefern JSON mit den üblichen HTTP-Statuscodes:
| Status | Bedeutung |
|---|---|
200 OK |
Anfrage erfolgreich (auch beim Anlegen einer Ressource – das angelegte Objekt steht im Body) |
204 No Content |
Ressource erfolgreich gelöscht |
Fehlerantworten
Abschnitt betitelt „Fehlerantworten“Fehler verwenden einen einheitlichen Umschlag: einen maschinenlesbaren Code error und ein für Menschen lesbares detail:
{ "error": "not_found", "detail": "bundle 'abc123' not found"}| Status | Code error |
Bedeutung |
|---|---|---|
401 |
unauthenticated |
Zugangsdaten fehlen, sind ungültig oder abgelaufen |
403 |
forbidden |
Ihnen fehlt die Berechtigung, oder die Zielressource gehört Ihnen nicht |
404 |
not_found |
Die Ressource existiert nicht (oder ist für Sie nicht sichtbar) |
409 |
conflict |
Gültige Anfrage, aber die Ressource ist noch nicht bereit (z. B. Vergleich eines Bundles, dessen Kette noch verarbeitet wird) – wiederholen Sie die Anfrage, wenn die Pipeline fertig ist |
422 |
validation_error |
Fehlerhafte Eingabe; detail enthält eine Liste von Problemen auf Feldebene |
OpenAPI-Spezifikation
Abschnitt betitelt „OpenAPI-Spezifikation“Die vollständige API-Spezifikation steht im Format OpenAPI 3.0 bereit:
GET /api/v1/openapi.jsonMit dieser Spezifikation können Sie typisierte API-Clients in Ihrer bevorzugten Programmiersprache erzeugen.
Gängige Workflows
Abschnitt betitelt „Gängige Workflows“Kampagnen automatisch anlegen
Abschnitt betitelt „Kampagnen automatisch anlegen“# 1. Create a projectPROJECT_ID=$(curl -s -X POST https://portor.<tenant>.askalot.io/api/v1/projects \ -H "X-Api-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "Q1 Survey"}' | jq -r '.id')
# 2. Create a questionnaire (the QML itself is the payload — there is no file to stage)QUESTIONNAIRE_ID=$(curl -s -X POST https://portor.<tenant>.askalot.io/api/v1/questionnaires \ -H "X-Api-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg p "$PROJECT_ID" --rawfile c feedback.qml \ '{name: "Customer Feedback", project_id: $p, content: $c}')" | jq -r '.id')
# 3. Create a campaigncurl -X POST https://portor.<tenant>.askalot.io/api/v1/campaigns \ -H "X-Api-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d "{\"name\": \"Q1 Campaign\", \"project_id\": \"$PROJECT_ID\", \"questionnaire_id\": \"$QUESTIONNAIRE_ID\", \"offers_ai_channel\": false}"Befragte aus Ihrem CRM importieren
Abschnitt betitelt „Befragte aus Ihrem CRM importieren“# Import respondents from a CSV or your CRM systemfor respondent in "${RESPONDENTS[@]}"; do curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondents \ -H "X-Api-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d "$respondent"done