API REST
Askalot propose une API REST qui donne accès par programmation à toutes les fonctionnalités de la plateforme. Elle vous permet d’automatiser vos processus d’enquête, de vous intégrer à des systèmes externes et de construire vos propres applications au-dessus de la plateforme Askalot.
Premiers pas
Section intitulée « Premiers pas »URL de base
Section intitulée « URL de base »https://portor.<tenant>.askalot.io/api/v1Remplacez <tenant> par le nom de tenant de votre organisation (par exemple portor.acme.askalot.io).
Authentification
Section intitulée « Authentification »Toutes les requêtes à l’API doivent être authentifiées au moyen d’un jeton API personnel.
Générer un jeton :
- Connectez-vous à
https://roundtable.<tenant>.askalot.io - Ouvrez « Paramètres du profil »
- Faites défiler jusqu’à la section « Jetons API »
- Cliquez sur « Générer un nouveau jeton »
- Copiez le jeton (il n’est affiché qu’une seule fois)
Utiliser votre jeton :
Placez votre jeton dans l’en-tête X-Api-Token :
curl -H "X-Api-Token: your_token_here" \ https://portor.<tenant>.askalot.io/api/v1/projectsPropriétés du jeton :
- Format : les jetons commencent par
aslat_(aslat_<32 characters>) ; ce préfixe permet aux outils de détection de secrets de repérer un commit accidentel. Seul le préfixe est conservé côté serveur à des fins d’identification : le jeton complet est affiché une fois à la création, puis plus jamais. - En-tête : envoyez-le dans l’en-tête
X-Api-Token. C’est la voie d’authentification de REST ; l’en-têteAuthorization: Bearerde Portor est réservé aux jetons d’accès OAuth (ceux que porte une session MCP, que REST accepte aussi), et non aux jetons API. - Portée : il authentifie uniquement l’API REST et n’est pas accepté par l’interface MCP. Un jeton appartient à l’organisation dans laquelle vous travailliez au moment de sa génération : chaque requête qu’il effectue agit dans cette organisation, avec les rôles que vous y détenez ; un rôle détenu dans une autre organisation ne s’applique pas. Pour travailler dans une autre organisation via REST, basculez vers celle-ci dans le navigateur et générez-y un jeton. Si un administrateur vous retire de cette organisation, ses jetons sont révoqués en même temps que votre adhésion.
- Révocation : révoquez un jeton à tout moment depuis « Paramètres du profil » ; la révocation prend effet immédiatement.
Durée de vie et renouvellement des jetons
Section intitulée « Durée de vie et renouvellement des jetons »Vous choisissez une date d’expiration lors de la création d’un jeton : la liste déroulante de « Paramètres du profil » propose 30 jours, 90 jours (par défaut) ou 1 an. L’expiration est obligatoire ; il n’existe pas d’option « sans expiration » pour les nouveaux jetons (seuls d’anciens jetons, conservés à titre dérogatoire, peuvent en être dépourvus).
- La page « Paramètres du profil » affiche la date d’expiration de chaque jeton et le nombre de jours restants, et signale qu’un jeton doit être renouvelé dès qu’il se trouve à moins de 14 jours de son expiration.
- Pour renouveler : créez un jeton de remplacement, mettez à jour votre intégration pour qu’elle l’utilise, puis révoquez l’ancien. Les jetons ne se renouvellent pas automatiquement : un jeton expiré renvoie
401et doit être remplacé.
Documentation interactive
Section intitulée « Documentation interactive »Explorez l’API de manière interactive avec Swagger UI à l’adresse :
https://portor.<tenant>.askalot.io/api/v1/docsLa documentation interactive vous permet de :
- Parcourir tous les points de terminaison disponibles
- Consulter les schémas des requêtes et des réponses
- Tester des appels à l’API directement dans votre navigateur
Ressources principales
Section intitulée « Ressources principales »Les projets sont les conteneurs de premier niveau qui organisent vos travaux de recherche par enquête.
| Méthode | Point de terminaison | Description |
|---|---|---|
GET |
/api/v1/projects |
Liste tous les projets |
POST |
/api/v1/projects |
Crée un nouveau projet |
GET |
/api/v1/projects/{id} |
Renvoie un projet par son identifiant |
PUT |
/api/v1/projects/{id} |
Met à jour un projet |
DELETE |
/api/v1/projects/{id} |
Supprime un projet |
POST |
/api/v1/projects/{id}/owners |
Ajoute des propriétaires au projet |
DELETE |
/api/v1/projects/{id}/owners |
Retire des propriétaires du projet |
Exemple : créer un projet
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" }'Réponse :
{ "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": []}Questionnaires
Section intitulée « Questionnaires »Les questionnaires définissent la structure de l’enquête en QML (Questionnaire Markup Language).
| Méthode | Point de terminaison | Description |
|---|---|---|
GET |
/api/v1/questionnaires |
Liste tous les questionnaires |
POST |
/api/v1/questionnaires |
Crée un nouveau questionnaire |
GET |
/api/v1/questionnaires/{id} |
Renvoie un questionnaire par son identifiant |
PUT |
/api/v1/questionnaires/{id} |
Met à jour un questionnaire |
DELETE |
/api/v1/questionnaires/{id} |
Supprime un questionnaire |
GET |
/api/v1/questionnaires/{id}/versions/{version_id}/translations |
Liste les traductions d’une version, par langue (complète, clés non traduites, figée, modifiée à la main) |
GET |
/api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} |
Renvoie la traduction dans une langue avec ses textes source |
PUT |
/api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} |
Enregistre du texte traduit (texts, base_updated_at) ; partiel, fusionné avec ce qui est stocké |
DELETE |
/api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} |
Supprime la traduction dans une langue (refusé une fois figée) |
Paramètres de requête :
project_id: filtre par projetstatus: filtre par statut (draft,active,paused,completed)
Campagnes
Section intitulée « Campagnes »Les campagnes relient les questionnaires aux répondants pour la collecte des données.
| Méthode | Point de terminaison | Description |
|---|---|---|
GET |
/api/v1/campaigns |
Liste toutes les campagnes |
POST |
/api/v1/campaigns |
Crée une nouvelle campagne |
GET |
/api/v1/campaigns/{id} |
Renvoie une campagne par son identifiant |
PUT |
/api/v1/campaigns/{id} |
Met à jour une campagne |
DELETE |
/api/v1/campaigns/{id} |
Supprime une campagne |
PUT |
/api/v1/campaigns/{id}/pool |
Affecte un vivier de répondants à la campagne |
GET |
/api/v1/campaigns/{id}/pool |
Renvoie le vivier affecté à la campagne |
PUT |
/api/v1/campaigns/{id}/questionnaire |
Change le questionnaire de la campagne |
POST |
/api/v1/campaigns/{id}/interviewers |
Ajoute des enquêteurs à la campagne |
DELETE |
/api/v1/campaigns/{id}/interviewers |
Retire des enquêteurs de la campagne |
Paramètres de requête :
project_id: filtre par projetquestionnaire_id: filtre par questionnairestatus: filtre par statutexpand=true: inclut les objets liés (projet, questionnaire, répondants)
Créer une campagne : POST /api/v1/campaigns exige name, project_id, questionnaire_id et offers_ai_channel. offers_ai_channel (booléen) indique si les répondants peuvent aussi répondre à l’enquête dans leur propre assistant IA. Il n’a pas de valeur par défaut, et une requête qui l’omet est refusée. Lorsqu’il vaut true, intro_text et consent_text sont également obligatoires. Voir Auto-entretien assisté par l’IA.
Modes de campagne :
Askalot prend en charge deux modes de campagne :
- Mode direct : les répondants remplissent les enquêtes de manière autonome grâce à des liens uniques
- Mode avec enquêteur : des enquêteurs administrent les enquêtes aux répondants par téléphone ou en face à face
Le mode est déterminé automatiquement selon que des enquêteurs sont affectés ou non à la campagne.
Chaque enquête enregistre aussi son propre mode (direct, ai_assisted ou field_interview) dans son champ mode. Une enquête est ai_assisted lorsque la campagne propose l’assistant IA et que le répondant y a donné son consentement avant de répondre.
Répondants
Section intitulée « Répondants »Les répondants sont les cibles de l’enquête, c’est-à-dire les personnes interrogées.
| Méthode | Point de terminaison | Description |
|---|---|---|
GET |
/api/v1/respondents |
Liste tous les répondants |
POST |
/api/v1/respondents |
Crée un nouveau répondant |
GET |
/api/v1/respondents/{id} |
Renvoie un répondant par son identifiant |
PUT |
/api/v1/respondents/{id} |
Met à jour un répondant |
DELETE |
/api/v1/respondents/{id} |
Supprime un répondant |
Paramètres de requête :
source_system: filtre par source (par exemplecrm,panel_provider)campaign_id: filtre par campagne
Remarque : les enquêteurs sont des utilisateurs ayant le rôle interviewer. Ils se gèrent via le point de terminaison /api/v1/users.
Exemple : importer un répondant
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"} }'Champs démographiques :
Les répondants peuvent porter des données démographiques utilisées pour le ciblage et l’analyse :
age: âge du répondantgender: identité de genrelocation: localisation géographique (texte libre, généralement"City, Country")external_id: l’identifiant dans votre systèmesource_system: source des données du répondantpreferred_language: langue préférée facultative (en,es,fr,de,hu), utilisée pour l’invitation et comme langue présélectionnée de l’enquête lorsque la campagne la propose
Une géographie plus fine que location (rue, ville, région, code postal, pays en valeurs distinctes) se place dans custom_attributes, et peut être désignée par custom_attributes.<key> partout où l’on peut nommer un attribut de répondant (facteurs d’échantillonnage, correspondances d’entrées externes). Une cible de calage nomme la colonne du jeu de données dans laquelle l’attribut a été extrait, _custom_<key>. Les clés supplémentaires de premier niveau sont ignorées plutôt que stockées : un export CRM qui envoie city comme champ à part perd donc cette valeur sans avertissement.
Enquêtes
Section intitulée « Enquêtes »Les enquêtes suivent chaque session d’enquête et ses réponses.
| Méthode | Point de terminaison | Description |
|---|---|---|
GET |
/api/v1/surveys |
Liste toutes les enquêtes |
POST |
/api/v1/surveys |
Crée une nouvelle session d’enquête |
GET |
/api/v1/surveys/{id} |
Renvoie une enquête par son identifiant |
PUT |
/api/v1/surveys/{id} |
Met à jour le statut d’une enquête |
DELETE |
/api/v1/surveys/{id} |
Supprime une enquête |
GET |
/api/v1/surveys/{id}/current-step |
Question courante + options + statut (Format de présentation des enquêtes) |
POST |
/api/v1/surveys/{id}/responses |
Soumet une réponse ; l’étape suivante est intégrée à la réponse |
POST |
/api/v1/surveys/{id}/finish |
Termine explicitement l’enquête (idempotent) |
Paramètres de requête :
questionnaire_id: filtre par questionnairecampaign_id: filtre par campagnerespondent_id: filtre par répondantstatus: filtre par statut (pending,in_progress,completed)expand=true: inclut les objets liés
Les réponses relatives aux enquêtes portent status ainsi qu’un booléen dérivé en lecture seule, completed (true exactement lorsque status vaut completed). L’achèvement s’exprime en mettant à jour status : il n’existe ni entrée ni paramètre de filtre completed.
Répondre à une enquête via POST /api/v1/surveys/{id}/responses est réservé aux tests et à la simulation : pour une enquête dont l’invitation a été envoyée, la requête est refusée, si bien qu’un entretien réel sur le terrain ne peut pas être écrit par programmation. Les réponses soumises de cette façon sont enregistrées comme produites par une machine, et leurs temps de réponse sont exclus de la détection des répondants trop rapides.
Viviers de répondants
Section intitulée « Viviers de répondants »Les viviers de répondants organisent les répondants en groupes réutilisables pour les campagnes.
| Méthode | Point de terminaison | Description |
|---|---|---|
GET |
/api/v1/respondent-pools |
Liste tous les viviers de répondants |
POST |
/api/v1/respondent-pools |
Crée un nouveau vivier |
GET |
/api/v1/respondent-pools/{id} |
Renvoie un vivier par son identifiant |
DELETE |
/api/v1/respondent-pools/{id} |
Supprime un vivier |
POST |
/api/v1/respondent-pools/{id}/respondents |
Ajoute des répondants au vivier |
DELETE |
/api/v1/respondent-pools/{id}/respondents |
Retire des répondants du vivier |
POST |
/api/v1/respondent-pools/generate |
Tire un vivier d’une stratégie d’échantillonnage (requested_size obligatoire) ; le vivier conserve ses paramètres de tirage |
POST |
/api/v1/respondent-pools/preview |
Prévisualise un tirage sans créer de vivier |
POST |
/api/v1/respondent-pools/{id}/refresh |
Tire à nouveau un vivier issu d’une stratégie, avec les paramètres de tirage qu’il a enregistrés |
Paramètres de requête :
project_id: filtre par projet
Stratégies d’échantillonnage
Section intitulée « Stratégies d’échantillonnage »Les stratégies d’échantillonnage définissent des distributions démographiques cibles pour constituer des échantillons représentatifs, ainsi que la manière d’évaluer l’adéquation à ces cibles. Une stratégie ne porte aucun paramètre de taille ni de sélection : ce sont des entrées de POST /api/v1/respondent-pools/generate, enregistrées sur le vivier qu’il crée.
| Méthode | Point de terminaison | Description |
|---|---|---|
GET |
/api/v1/sampling-strategies |
Liste toutes les stratégies |
POST |
/api/v1/sampling-strategies |
Crée une nouvelle stratégie |
GET |
/api/v1/sampling-strategies/{id} |
Renvoie une stratégie par son identifiant |
PUT |
/api/v1/sampling-strategies/{id} |
Met à jour une stratégie |
DELETE |
/api/v1/sampling-strategies/{id} |
Supprime une stratégie |
Paramètres de requête :
project_id: filtre par projet
Exemple : créer une stratégie d’échantillonnage
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} } ] }'Exemple : tirer un vivier de la stratégie
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 est obligatoire ; oversample_factor (1.0 par défaut), selection_algorithm (greedy ou random_constrained, greedy par défaut), require_email (false par défaut) et exclude_respondent_ids (aucun par défaut) sont facultatifs. Tirez un second vivier de la même stratégie, à une autre taille, chaque fois que vous en avez besoin.
Un lot associe un projet → un questionnaire → un sous-ensemble choisi de campagnes à une chaîne linéaire unique de jeux de données Bronze → Silver → Gold : c’est l’unité autour de laquelle s’organise le tableau du pipeline de Balansor.
| Méthode | Point de terminaison | Description |
|---|---|---|
GET |
/api/v1/bundles |
Liste tous les lots |
POST |
/api/v1/bundles |
Crée un nouveau lot |
GET |
/api/v1/bundles/{id} |
Détail d’un lot, y compris les recettes de ses étapes (cibles de calage Silver, opérations Gold) |
DELETE |
/api/v1/bundles/{id} |
Supprime un lot (et sa chaîne de jeux de données) |
POST |
/api/v1/bundles/{id}/clone |
Clone un lot en profondeur : les jeux de données prêts et les recettes des étapes sont repris |
GET |
/api/v1/bundles/{id}/quality |
Le bilan de représentativité du lot (sélection, terrain, pondération, écart dû au terrain, réponse) |
GET |
/api/v1/bundles/{id}/comparison |
Comparaison Bronze-Silver (409 conflict tant que les deux étapes ne sont pas ready) |
GET |
/api/v1/bundles/{id}/coding |
État du codage des questions ouvertes : les candidats au codage que propose le jeu de données Bronze, la sélection de questions de l’analyste et, par question, les dimensions proposées avec leurs catégories et leur état de sélection (le choix des dimensions qui deviennent des colonnes reste dans l’interface de Balansor) |
PUT |
/api/v1/bundles/{id}/coding/selection |
Définit les unités de texte ouvert que ce lot code : l’ensemble complet des clés d’unités, qui remplace le précédent (rôle Gestionnaire, utilisateur identifié requis) |
POST |
/api/v1/bundles/{id}/strategy |
Affecte ou retire la stratégie d’échantillonnage courante du lot (rôle Gestionnaire, utilisateur identifié requis) |
PUT |
/api/v1/bundles/{id}/targets |
Modifie les cibles de calage du lot, c’est-à-dire la spécification de pondération Silver, chaque cible étant raked ou benchmark (rôle Gestionnaire, utilisateur identifié requis) |
GET |
/api/v1/bundles/{id}/targets/copy-preview?source_bundle_id={source} |
Prévisualise la copie des cibles de calage d’un autre lot dans celui-ci : addable et rejected, avec les motifs ; n’écrit rien (rôle Gestionnaire) |
Paramètres de requête :
project_id: filtre par projet
Les opérations d’étape (extraction, codage + pondération, affinage, export) se pilotent avec les outils MCP de lot et de jeux de données : voir mcp-bundle-tools.md et mcp-dataset-tools.md pour la référence complète des paramètres de qualité et d’étape.
Format des réponses
Section intitulée « Format des réponses »Réponses en cas de succès
Section intitulée « Réponses en cas de succès »Toutes les réponses réussies renvoient du JSON avec les codes de statut HTTP standard :
| Statut | Signification |
|---|---|
200 OK |
La requête a abouti (y compris la création d’une ressource : l’objet créé est renvoyé dans le corps) |
204 No Content |
Ressource supprimée avec succès |
Réponses en cas d’erreur
Section intitulée « Réponses en cas d’erreur »Les erreurs utilisent une enveloppe unique, composée d’un code error lisible par une machine et d’un detail lisible par un humain :
{ "error": "not_found", "detail": "bundle 'abc123' not found"}| Statut | Code error |
Signification |
|---|---|---|
401 |
unauthenticated |
Identifiants absents, invalides ou expirés |
403 |
forbidden |
Vous n’avez pas la capacité requise, ou vous n’êtes pas propriétaire de la ressource visée |
404 |
not_found |
La ressource n’existe pas (ou ne vous est pas visible) |
409 |
conflict |
Requête valide, mais la ressource n’est pas encore prête (par exemple, comparer un lot dont la chaîne est encore en cours de traitement) : réessayez une fois le pipeline terminé |
422 |
validation_error |
Entrée mal formée ; detail contient la liste des problèmes par champ |
Spécification OpenAPI
Section intitulée « Spécification OpenAPI »La spécification complète de l’API est disponible au format OpenAPI 3.0 :
GET /api/v1/openapi.jsonServez-vous de cette spécification pour générer des clients d’API typés dans le langage de programmation de votre choix.
Scénarios courants
Section intitulée « Scénarios courants »Automatiser la création d’une campagne
Section intitulée « Automatiser la création d’une campagne »# 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}"Importer des répondants depuis votre CRM
Section intitulée « Importer des répondants depuis votre CRM »# 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