Tovább a tartalomhoz
Tudástár

REST API

Az Askalot REST API-t kínál a platform összes képességének programozott eléréséhez. Az API-val automatizálhatja a kérdőíves munkafolyamatokat, külső rendszerekkel integrálhatja a platformot, és saját alkalmazásokat építhet az Askalotra.

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

A <tenant> helyére a szervezete bérlőjének nevét írja (például portor.acme.askalot.io).

Minden API-kérést személyes API-tokennel kell hitelesíteni.

Token létrehozása:

  1. Jelentkezzen be a https://roundtable.<tenant>.askalot.io címen
  2. Lépjen a Profilbeállítások oldalra
  3. Görgessen az „API-tokenek” szakaszhoz
  4. Kattintson az „Új token létrehozása” gombra
  5. Másolja ki a tokent (csak egyszer jelenik meg)

A token használata:

Küldje a tokent az X-Api-Token fejlécben:

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

A token tulajdonságai:

  • Formátum: a tokenek aslat_ előtaggal kezdődnek (aslat_<32 characters>); az előtag alapján a titokkereső eszközök kiszúrhatják a véletlenül verziókezelőbe került tokent. A szerver azonosítás céljából csak az előtagot tárolja – a teljes token csak egyszer, a létrehozáskor jelenik meg, és soha többé.
  • Fejléc: az X-Api-Token fejlécben küldje. Ez a REST hitelesítési módja; a Portor Authorization: Bearer fejléce az OAuth-hozzáférési tokeneknek van fenntartva (azoknak, amelyeket egy MCP-munkamenet hordoz, és amelyeket a REST is elfogad), nem az API-tokeneknek.
  • Hatókör: csak a REST API-t hitelesíti, az MCP-felület nem fogadja el. A token ahhoz a szervezethez tartozik, amelyben Ön a token létrehozásakor dolgozott: minden kérése abban a szervezetben fut, az ott betöltött szerepköreivel – a más szervezetben betöltött szerepkör nem érvényes. Ha REST-en keresztül egy másik szervezetben szeretne dolgozni, váltson át oda a böngészőben, és ott hozzon létre tokent. Ha egy adminisztrátor eltávolítja Önt abból a szervezetből, a rendszer a tagsággal együtt az ottani tokenjeit is visszavonja.
  • Visszavonás: bármikor visszavonhatja a Profilbeállításokban; a visszavonás azonnal érvénybe lép.

A token létrehozásakor Ön választja meg a lejáratot – a Profilbeállítások legördülő listája 30 nap, 90 nap (az alapértelmezés) és 1 év lehetőséget kínál. A lejárat megadása kötelező; az új tokenekhez nincs „soha le nem járó” lehetőség (csak a régebbi, korábbi szabályok szerint létrehozott tokeneknek hiányozhat a lejárata).

  • A Profilbeállítások minden tokennél megmutatja a lejárat dátumát és a hátralévő napok számát, és cserére jelöli a tokent, ha a lejáratáig 14 napnál kevesebb van hátra.
  • A csere menete: hozzon létre egy helyettesítő tokent, állítsa át rá az integrációját, majd vonja vissza a régit. A tokenek nem újulnak meg automatikusan – a lejárt token 401 választ kap, és le kell cserélni.

Az API-t interaktívan a Swagger UI-ban fedezheti fel:

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

Az interaktív dokumentációban:

  • böngészheti az összes elérhető végpontot,
  • megtekintheti a kérések és válaszok sémáit,
  • közvetlenül a böngészőből kipróbálhatja az API-hívásokat.

A projektek a kérdőíves kutatás szervezésére szolgáló legfelső szintű tárolók.

Metódus Végpont Leírás
GET /api/v1/projects Az összes projekt listázása
POST /api/v1/projects Új projekt létrehozása
GET /api/v1/projects/{id} Projekt lekérése azonosító alapján
PUT /api/v1/projects/{id} Projekt módosítása
DELETE /api/v1/projects/{id} Projekt törlése
POST /api/v1/projects/{id}/owners Projekttulajdonosok felvétele
DELETE /api/v1/projects/{id}/owners Projekttulajdonosok eltávolítása

Példa: projekt létrehozása

Terminál
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"
}'

Válasz:

{
"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": []
}

A kérdőív szerkezetét a QML (Questionnaire Markup Language) írja le.

Metódus Végpont Leírás
GET /api/v1/questionnaires Az összes kérdőív listázása
POST /api/v1/questionnaires Új kérdőív létrehozása
GET /api/v1/questionnaires/{id} Kérdőív lekérése azonosító alapján
PUT /api/v1/questionnaires/{id} Kérdőív módosítása
DELETE /api/v1/questionnaires/{id} Kérdőív törlése
GET /api/v1/questionnaires/{id}/versions/{version_id}/translations Egy verzió fordításainak listázása nyelvenként (teljes-e, lefordítatlan kulcsok, befagyasztott, ember által szerkesztett)
GET /api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} Egy nyelv fordításának lekérése a forrásszövegeivel együtt
PUT /api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} Lefordított szöveg mentése (texts, base_updated_at); részleges, a tárolt fordítással összefésülve
DELETE /api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} Egy nyelv fordításának törlése (befagyasztás után elutasítva)

Lekérdezési paraméterek:

  • project_id – szűrés projekt szerint
  • status – szűrés állapot szerint (draft, active, paused, completed)

A kampányok az adatgyűjtéshez kapcsolják össze a kérdőíveket a válaszadókkal.

Metódus Végpont Leírás
GET /api/v1/campaigns Az összes kampány listázása
POST /api/v1/campaigns Új kampány létrehozása
GET /api/v1/campaigns/{id} Kampány lekérése azonosító alapján
PUT /api/v1/campaigns/{id} Kampány módosítása
DELETE /api/v1/campaigns/{id} Kampány törlése
PUT /api/v1/campaigns/{id}/pool Válaszadói kör hozzárendelése a kampányhoz
GET /api/v1/campaigns/{id}/pool A kampányhoz rendelt válaszadói kör lekérése
PUT /api/v1/campaigns/{id}/questionnaire A kampány kérdőívének módosítása
POST /api/v1/campaigns/{id}/interviewers Kérdezők felvétele a kampányba
DELETE /api/v1/campaigns/{id}/interviewers Kérdezők eltávolítása a kampányból

Lekérdezési paraméterek:

  • project_id – szűrés projekt szerint
  • questionnaire_id – szűrés kérdőív szerint
  • status – szűrés állapot szerint
  • expand=true – a kapcsolódó objektumok (projekt, kérdőív, válaszadók) beemelése

Kampány létrehozása: a POST /api/v1/campaigns kéréshez kötelező a name, a project_id, a questionnaire_id és az offers_ai_channel. Az offers_ai_channel (logikai érték) azt adja meg, hogy a válaszadók a saját MI-asszisztensükben is kitölthetik-e a kérdőívet. Nincs alapértéke, és a nélküle küldött kérést a rendszer elutasítja. Ha true, az intro_text és a consent_text is kötelező. Lásd: MI-asszisztált önkitöltés.

Kampánymódok:

Az Askalot kétféle kampánymódot támogat:

  • Közvetlen mód: a válaszadók egyedi linkeken keresztül, önállóan töltik ki a kérdőíveket
  • Kérdezős mód: a kérdezők telefonon vagy személyesen veszik fel a kérdőívet a válaszadókkal

A mód automatikusan dől el aszerint, hogy rendeltek-e kérdezőket a kampányhoz.

Minden kitöltés a saját módját is rögzíti (direct, ai_assisted vagy field_interview) a mode mezőjében. Egy kitöltés akkor ai_assisted, ha a kampány felkínálja az MI-asszisztenst, és a válaszadó a válaszadás előtt ott adta meg a beleegyezését.

A válaszadók a kérdőívek célszemélyei – azok az emberek, akiket megkérdeznek.

Metódus Végpont Leírás
GET /api/v1/respondents Az összes válaszadó listázása
POST /api/v1/respondents Új válaszadó létrehozása
GET /api/v1/respondents/{id} Válaszadó lekérése azonosító alapján
PUT /api/v1/respondents/{id} Válaszadó módosítása
DELETE /api/v1/respondents/{id} Válaszadó törlése

Lekérdezési paraméterek:

  • source_system – szűrés forrás szerint (például crm, panel_provider)
  • campaign_id – szűrés kampány szerint

Megjegyzés: A kérdezők interviewer szerepkörű felhasználók. Őket az /api/v1/users végponton keresztül kezelheti.

Példa: válaszadó importálása

Terminál
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"}
}'

Demográfiai mezők:

A válaszadókhoz demográfiai adatok tárolhatók a célzáshoz és az elemzéshez:

  • age – a válaszadó életkora
  • gender – nemi identitás
  • location – földrajzi hely (szabad szöveg, jellemzően "City, Country" formában)
  • external_id – az Ön rendszerének azonosítója
  • source_system – a válaszadói adatok forrása
  • preferred_language – opcionális preferált nyelv (en, es, fr, de, hu); ezen a nyelven készül a meghívó, és ez lesz a kérdőív előre kiválasztott nyelve, ha a kampány kínálja

A location mezőnél finomabb földrajzi adat – utca, város, állam, irányítószám, ország külön értékként – a custom_attributes mezőbe kerül, és mindenhol custom_attributes.<key> formában hivatkozható, ahol válaszadói attribútum megnevezhető (mintavételi tényezők, külső bemeneti leképezések). A kalibrációs célérték azt az adatkészlet-oszlopot nevezi meg, amelybe az attribútumot kinyerték: _custom_<key>. A további felső szintű kulcsokat a rendszer nem tárolja, hanem figyelmen kívül hagyja, így egy olyan CRM-export, amely a city értéket külön mezőként küldi, ezt az értéket észrevétlenül elveszíti.

A kitöltések az egyes kérdőív-kitöltési munkameneteket és a válaszokat követik nyomon.

Metódus Végpont Leírás
GET /api/v1/surveys Az összes kitöltés listázása
POST /api/v1/surveys Új kitöltési munkamenet létrehozása
GET /api/v1/surveys/{id} Kitöltés lekérése azonosító alapján
PUT /api/v1/surveys/{id} Kitöltés állapotának módosítása
DELETE /api/v1/surveys/{id} Kitöltés törlése
GET /api/v1/surveys/{id}/current-step Az aktuális kérdés + válaszlehetőségek + állapot (A kérdőív megjelenítési formátuma)
POST /api/v1/surveys/{id}/responses Válasz beküldése; a következő lépés a válaszban érkezik
POST /api/v1/surveys/{id}/finish A kitöltés kifejezett lezárása (idempotens)

Lekérdezési paraméterek:

  • questionnaire_id – szűrés kérdőív szerint
  • campaign_id – szűrés kampány szerint
  • respondent_id – szűrés válaszadó szerint
  • status – szűrés állapot szerint (pending, in_progress, completed)
  • expand=true – a kapcsolódó objektumok beemelése

A kitöltésekről adott API-válaszok a status mellett egy származtatott, írásvédett completed logikai értéket is tartalmaznak (pontosan akkor true, ha a status értéke completed). A befejezést a status módosítása fejezi ki – nincs completed bemeneti vagy szűrőparaméter.

A kérdőív kitöltése a POST /api/v1/surveys/{id}/responses végponton keresztül tesztelésre és szimulációra korlátozódik: azt a kitöltést, amelyhez már meghívót küldtek, a rendszer elutasítja, így egy élő terepmunka-interjúba programozottan nem lehet írni. Az így beküldött válaszokat a rendszer gépi előállításúként rögzíti, és a válaszidejük kimarad a túl gyors kitöltők észleléséből.

A válaszadói körök a válaszadókat több kampányban is felhasználható csoportokba rendezik.

Metódus Végpont Leírás
GET /api/v1/respondent-pools Az összes válaszadói kör listázása
POST /api/v1/respondent-pools Új válaszadói kör létrehozása
GET /api/v1/respondent-pools/{id} Válaszadói kör lekérése azonosító alapján
DELETE /api/v1/respondent-pools/{id} Válaszadói kör törlése
POST /api/v1/respondent-pools/{id}/respondents Válaszadók felvétele a válaszadói körbe
DELETE /api/v1/respondent-pools/{id}/respondents Válaszadók eltávolítása a válaszadói körből
POST /api/v1/respondent-pools/generate Válaszadói kör húzása egy mintavételi stratégiából (a requested_size kötelező); a válaszadói kör eltárolja a húzás beállításait
POST /api/v1/respondent-pools/preview Egy húzás előnézete válaszadói kör létrehozása nélkül
POST /api/v1/respondent-pools/{id}/refresh Egy stratégiából húzott válaszadói kör újrahúzása a saját tárolt húzási beállításaival

Lekérdezési paraméterek:

  • project_id – szűrés projekt szerint

A mintavételi stratégiák a reprezentatív minták létrehozásához szükséges demográfiai célmegoszlásokat határozzák meg, valamint azt, hogyan kell értékelni az ezekhez való illeszkedést. A stratégia nem tartalmaz méretet vagy kiválasztási beállítást: ezek a POST /api/v1/respondent-pools/generate bemenetei, és a rendszer az így létrehozott válaszadói körrel együtt tárolja őket.

Metódus Végpont Leírás
GET /api/v1/sampling-strategies Az összes stratégia listázása
POST /api/v1/sampling-strategies Új stratégia létrehozása
GET /api/v1/sampling-strategies/{id} Stratégia lekérése azonosító alapján
PUT /api/v1/sampling-strategies/{id} Stratégia módosítása
DELETE /api/v1/sampling-strategies/{id} Stratégia törlése

Lekérdezési paraméterek:

  • project_id – szűrés projekt szerint

Példa: mintavételi stratégia létrehozása

Terminál
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}
}
]
}'

Példa: válaszadói kör húzása a stratégiából

Terminál
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
}'

A requested_size kötelező; az oversample_factor (alapértelmezés: 1.0), a selection_algorithm (greedy vagy random_constrained, alapértelmezés: greedy), a require_email (alapértelmezés: false) és az exclude_respondent_ids (alapértelmezés: nincs) opcionális. Ha szüksége van rá, ugyanabból a stratégiából bármikor húzhat egy második, eltérő méretű válaszadói kört is.

A csomag egy projektet → egy kérdőívet → a kampányok kiválasztott részhalmazát köti egyetlen lineáris Bronz → Ezüst → Arany adatkészlet-lánchoz – ez az az egység, amely köré a Balansor adatfolyam-táblája szerveződik.

Metódus Végpont Leírás
GET /api/v1/bundles Az összes csomag listázása
POST /api/v1/bundles Új csomag létrehozása
GET /api/v1/bundles/{id} Csomag részletei, a fázisreceptekkel együtt (Ezüst kalibrációs célértékek, Arany műveletek)
DELETE /api/v1/bundles/{id} Csomag törlése (az adatkészlet-láncával együtt)
POST /api/v1/bundles/{id}/clone Csomag klónozása – mély másolat: a kész adatkészletek és a fázisreceptek is átkerülnek
GET /api/v1/bundles/{id}/quality A csomag reprezentativitásának alakulása (kiválasztás, terepen megvalósult, súlyozott, terepmunka-eltolódás, válaszadás)
GET /api/v1/bundles/{id}/comparison A Bronz és az Ezüst adatkészlet összehasonlítása (409 conflict, amíg mindkét fázis nem ready)
GET /api/v1/bundles/{id}/coding A nyitott válaszok kódolásának állapota – a Bronz adatkészlet által kínált kódolási jelöltek, az elemző kérdésválasztása, valamint kérdésenként a javasolt dimenziók a kategóriáikkal és a kiválasztásuk állapotával (hogy mely dimenziókból lesznek oszlopok, azt továbbra is a Balansor felületén kell eldönteni)
PUT /api/v1/bundles/{id}/coding/selection Annak beállítása, mely nyitott szöveges egységeket kódolja ez a csomag – az egységkulcsok teljes halmaza, amely felváltja a korábbit (menedzser szerepkör, azonosított felhasználó szükséges)
POST /api/v1/bundles/{id}/strategy A csomag aktuális mintavételi stratégiájának hozzárendelése vagy törlése (menedzser szerepkör, azonosított felhasználó szükséges)
PUT /api/v1/bundles/{id}/targets A csomag kalibrációs célértékeinek szerkesztése – ez az Ezüst adatkészlet súlyozási specifikációja, mindegyik célérték raked vagy benchmark (menedzser szerepkör, azonosított felhasználó szükséges)
GET /api/v1/bundles/{id}/targets/copy-preview?source_bundle_id={source} Egy másik csomag kalibrációs célértékeinek erre a csomagra való másolásának előnézete: addable és rejected, indoklással; semmit sem ír (menedzser szerepkör)

Lekérdezési paraméterek:

  • project_id – szűrés projekt szerint

A fázisműveleteket (kinyerés, kódolás + súlyozás, finomítás, export) az MCP csomag- és adatkészlet-eszközei vezérlik – a teljes minőségi és fázisparaméter-referenciát lásd az mcp-bundle-tools.md és az mcp-dataset-tools.md oldalon.

Minden sikeres válasz JSON formátumú, szabványos HTTP-állapotkóddal:

Állapot Jelentés
200 OK A kérés sikeres volt (az erőforrás létrehozását is beleértve – a létrehozott objektum a válasz törzsében érkezik)
204 No Content Az erőforrás törlése sikeres volt

A hibák egységes borítékot használnak: egy géppel olvasható error kódot és egy ember számára olvasható detail leírást:

{
"error": "not_found",
"detail": "bundle 'abc123' not found"
}
Állapot error kód Jelentés
401 unauthenticated Hiányzó, érvénytelen vagy lejárt hitelesítő adat
403 forbidden Nincs meg a szükséges képessége, vagy nem Ön a célerőforrás tulajdonosa
404 not_found Az erőforrás nem létezik (vagy Ön nem láthatja)
409 conflict A kérés érvényes, de az erőforrás még nem áll készen (például olyan csomag összehasonlítása, amelynek a lánca még feldolgozás alatt áll) – próbálja újra, miután az adatfolyam befejeződött
422 validation_error Hibás bemenet; a detail mezőnkénti hibák listáját tartalmazza

A teljes API-specifikáció OpenAPI 3.0 formátumban érhető el:

GET /api/v1/openapi.json

Ebből a specifikációból típusos API-klienseket generálhat a kívánt programozási nyelven.

Terminál
# 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}"

Válaszadók importálása a CRM-rendszeréből

Szekció neve “Válaszadók importálása a CRM-rendszeréből”
Terminál
# 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