Zum Inhalt springen
Wissensdatenbank

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.

https://portor.<tenant>.askalot.io/api/v1

Ersetzen Sie <tenant> durch den Tenant-Namen Ihrer Organisation (z. B. portor.acme.askalot.io).

Jede API-Anfrage muss mit einem persönlichen API-Token authentifiziert werden.

Ein Token erzeugen:

  1. Melden Sie sich bei https://roundtable.<tenant>.askalot.io an
  2. Öffnen Sie die Profileinstellungen
  3. Scrollen Sie zum Abschnitt „API-Tokens“
  4. Klicken Sie auf „Neues Token erzeugen“
  5. Kopieren Sie das Token (es wird nur einmal angezeigt)

Das Token verwenden:

Senden Sie Ihr Token im Header X-Api-Token:

Terminal-Fenster
curl -H "X-Api-Token: your_token_here" \
https://portor.<tenant>.askalot.io/api/v1/projects

Eigenschaften 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 Header Authorization: Bearer ist 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.

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 401 und muss ersetzt werden.

Erkunden Sie die API interaktiv mit Swagger UI unter:

https://portor.<tenant>.askalot.io/api/v1/docs

In der interaktiven Dokumentation können Sie:

  • alle verfügbaren Endpunkte durchsehen
  • Anfrage- und Antwortschemas ansehen
  • API-Aufrufe direkt im Browser testen

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

Terminal-Fenster
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 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 filtern
  • status – nach Status filtern (draft, active, paused, completed)

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 filtern
  • questionnaire_id – nach Fragebogen filtern
  • status – nach Status filtern
  • expand=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 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

Terminal-Fenster
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 Person
  • gender – Geschlechtsidentität
  • location – geografischer Ort (Freitext, typischerweise "City, Country")
  • external_id – die Kennung in Ihrem System
  • source_system – Herkunft der Befragtendaten
  • preferred_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 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 filtern
  • campaign_id – nach Kampagne filtern
  • respondent_id – nach befragter Person filtern
  • status – 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 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 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

Terminal-Fenster
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

Terminal-Fenster
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.

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.

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

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

Die vollständige API-Spezifikation steht im Format OpenAPI 3.0 bereit:

GET /api/v1/openapi.json

Mit dieser Spezifikation können Sie typisierte API-Clients in Ihrer bevorzugten Programmiersprache erzeugen.

Terminal-Fenster
# 1. Create a project
PROJECT_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 campaign
curl -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}"
Terminal-Fenster
# Import respondents from a CSV or your CRM system
for 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