Ekenno Developer Portal & Survey API

01. Catégories scope: categories:read scope: surveys:read

GET /api/surveys/categories/

Lister les catégories actives

Retourne toutes les catégories de sondages actives avec leur identifiant UUID, slug, icône et couleur.

Cet endpoint ne requiert aucun paramètre de corps ou de query obligatoire.

curl -X GET "https://docs.ekenno.com/api/surveys/categories/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://docs.ekenno.com/api/surveys/categories/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/categories/", {
  method: "GET",
  headers: {
    "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Accept": "application/json"
  }
});
const categories = await response.json();
console.log(categories);

200 OK Exemple de réponse JSON

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Technologie & Innovation",
    "slug": "technologie",
    "icon": "bx-laptop",
    "color": "#3b82f6",
    "is_active": true,
    "order": 1
  }
]

02. Sondages (Manage) scope: surveys:read

GET /api/surveys/manage/

Guide détaillé

Lister vos sondages

Retourne la liste paginée des sondages appartenant à votre compte ou workspace avec filtres par statut, catégorie et recherche.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
status	query	string	Filtrer par statut : draft, active, paused, closed.
search	query	string	Recherche plein texte dans title et description.
category	query	UUID \| slug	Filtrer par UUID ou slug de catégorie.
page	query	integer	Numéro de page (20 résultats par page).

curl -X GET "https://docs.ekenno.com/api/surveys/manage/?status=active" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://docs.ekenno.com/api/surveys/manage/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    params={"status": "active"},
    timeout=10,
)
print(response.json())

const url = new URL("https://docs.ekenno.com/api/surveys/manage/");
url.searchParams.set("status", "active");

const response = await fetch(url, {
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
const data = await response.json();
console.log(data);

200 OK Exemple de réponse JSON

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
      "title": "Enquête Satisfaction Mobile 2026",
      "status": "active",
      "version_number": 1,
      "max_responses": 500,
      "current_responses": 142,
      "question_count": 8,
      "completion_rate": 88.5,
      "share_token": "ek98a7b6c5d4",
      "public_url": "https://ekenno.com/s/ek98a7b6c5d4/",
      "embed_url": "https://ekenno.com/survey/368de50f-5df6-4b15-b6cf-f5ff6d123c90/embed/"
    }
  ]
}

02. Sondages (Manage) scope: surveys:write

POST /api/surveys/manage/

Guide détaillé

Créer un nouveau sondage

Crée un sondage à l'état draft avec génération automatique du share_token public et de l'URL d'intégration embed.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
title Requis	body	string	Titre public du sondage.
description	body	string	Description et consignes d'introduction.
category_id	body	UUID	UUID de la catégorie (alias accepté : category).
survey_type	body	string	internal (défaut), external ou embed.
estimated_time	body	integer	Durée estimée en minutes (défaut : 5).
max_responses	body	integer	Quota maximal de réponses (0 = illimité).
allow_anonymous	body	boolean	Autoriser les réponses sans compte sur /s/<token>/.
collect_email	body	boolean	Demander l'email aux répondants anonymes.

curl -X POST "https://docs.ekenno.com/api/surveys/manage/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Baromètre Expérience Client Q4",
    "description": "Évaluation de nos nouveaux services digitaux",
    "category_id": "550e8400-e29b-41d4-a716-446655440000",
    "survey_type": "internal",
    "estimated_time": 4,
    "max_responses": 500,
    "allow_anonymous": true,
    "collect_email": true
  }'

import requests

payload = {
    "title": "Baromètre Expérience Client Q4",
    "description": "Évaluation de nos nouveaux services digitaux",
    "category_id": "550e8400-e29b-41d4-a716-446655440000",
    "survey_type": "internal",
    "estimated_time": 4,
    "max_responses": 500,
    "allow_anonymous": True,
    "collect_email": True,
}
response = requests.post(
    "https://docs.ekenno.com/api/surveys/manage/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json=payload,
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    title: "Baromètre Expérience Client Q4",
    description: "Évaluation de nos nouveaux services digitaux",
    category_id: "550e8400-e29b-41d4-a716-446655440000",
    survey_type: "internal",
    estimated_time: 4,
    max_responses: 500,
    allow_anonymous: true,
    collect_email: true
  })
});
const survey = await response.json();
console.log("Created survey:", survey.id);

201 Created Exemple de réponse JSON

{
  "id": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
  "title": "Baromètre Expérience Client Q4",
  "status": "draft",
  "status_display": "Draft",
  "version_number": 1,
  "estimated_time": 4,
  "max_responses": 500,
  "allow_anonymous": true,
  "collect_email": true,
  "share_token": "ek98a7b6c5d4",
  "public_url": "https://ekenno.com/s/ek98a7b6c5d4/",
  "embed_url": "https://ekenno.com/survey/368de50f-5df6-4b15-b6cf-f5ff6d123c90/embed/",
  "questions": [],
  "eligibility_rules": []
}

02. Sondages (Manage) scope: surveys:read

GET /api/surveys/manage/{id}/

Guide détaillé

Récupérer les détails d'un sondage

Retourne la configuration complète d'un sondage, ses questions ordonnées, ses règles d'éligibilité et ses URLs de diffusion.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
id Requis	path	UUID	Identifiant UUID du sondage.

curl -X GET "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

import requests

survey_id = "368de50f-5df6-4b15-b6cf-f5ff6d123c90"
response = requests.get(
    f"https://docs.ekenno.com/api/surveys/manage/{survey_id}/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.json())

const surveyId = "368de50f-5df6-4b15-b6cf-f5ff6d123c90";
const response = await fetch(`https://docs.ekenno.com/api/surveys/manage/${surveyId}/`, {
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
const survey = await response.json();
console.log(survey);

200 OK Exemple de réponse JSON

{
  "id": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
  "title": "Baromètre Expérience Client Q4",
  "status": "active",
  "version_number": 1,
  "question_count": 2,
  "response_count": 142,
  "completion_rate": 88.5,
  "share_token": "ek98a7b6c5d4",
  "questions": [
    {
      "id": "8e3678fb-2917-4824-9b88-c711aa110022",
      "question_text": "Quelle est votre note globale ?",
      "question_type": "stars",
      "order": 1,
      "is_required": true
    }
  ],
  "eligibility_rules": []
}

02. Sondages (Manage) scope: surveys:write

PATCH /api/surveys/manage/{id}/

Guide détaillé

Mettre à jour un sondage

Modifie partiellement les métadonnées, les quotas ou les options d'accès d'un sondage.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
id Requis	path	UUID	Identifiant UUID du sondage.
title	body	string	Nouveau titre du sondage.
max_responses	body	integer	Nouveau quota maximal de réponses.

curl -X PATCH "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"max_responses": 1000}'

import requests

response = requests.patch(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={"max_responses": 1000},
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ max_responses: 1000 })
});
console.log(await response.json());

200 OK Exemple de réponse JSON

{
  "id": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
  "title": "Baromètre Expérience Client Q4",
  "max_responses": 1000,
  "status": "draft"
}

02. Sondages (Manage) scope: surveys:write

POST /api/surveys/manage/{id}/publish/

Guide détaillé

Publier un sondage

Vérifie que le sondage contient au moins une question et passe son statut à active avec horodatage published_at.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
id Requis	path	UUID	Identifiant UUID du sondage à publier.

curl -X POST "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/publish/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

import requests

response = requests.post(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/publish/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/publish/", {
  method: "POST",
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
console.log(await response.json());

200 OK Exemple de réponse JSON

{
  "message": "Survey published successfully.",
  "survey": {
    "id": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
    "status": "active",
    "is_available": true,
    "published_at": "2026-11-12T16:00:00Z"
  }
}

02. Sondages (Manage) scope: surveys:write

POST /api/surveys/manage/{id}/pause/

Guide détaillé

Mettre un sondage en pause

Suspend temporairement la collecte de réponses sur un sondage actif (passage à l'état paused).

Paramètres de la requête

Paramètre	Emplacement	Type	Description
id Requis	path	UUID	Identifiant UUID du sondage actif.

curl -X POST "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/pause/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"

import requests

response = requests.post(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/pause/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/pause/", {
  method: "POST",
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
console.log(await response.json());

200 OK Exemple de réponse JSON

{
  "message": "Survey paused successfully.",
  "survey": {
    "id": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
    "status": "paused",
    "is_available": false
  }
}

02. Sondages (Manage) scope: surveys:write

POST /api/surveys/manage/{id}/close/

Guide détaillé

Clôturer définitivement un sondage

Ferme définitivement un sondage (statut closed). Les réponses existantes restent consultables et exportables.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
id Requis	path	UUID	Identifiant UUID du sondage.

curl -X POST "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/close/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"

import requests

response = requests.post(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/close/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/close/", {
  method: "POST",
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
console.log(await response.json());

200 OK Exemple de réponse JSON

{
  "message": "Survey closed successfully.",
  "survey": {
    "id": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
    "status": "closed",
    "is_available": false
  }
}

02. Sondages (Manage) scope: surveys:delete

DELETE /api/surveys/manage/{id}/

Guide détaillé

Supprimer un sondage

Supprime définitivement un sondage et ses questions associées.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
id Requis	path	UUID	Identifiant UUID du sondage.

curl -X DELETE "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"

import requests

response = requests.delete(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.status_code)  # 204

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/", {
  method: "DELETE",
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
console.log("Deleted:", response.status === 204);

204 No Content Exemple de réponse JSON

// 204 No Content (aucun corps retourné)

03. Questions (32 Types) scope: surveys:read scope: questions:write

GET /api/surveys/manage/{survey_id}/questions/

Guide détaillé

Lister les questions d'un sondage

Retourne toutes les questions ordonnées d'un sondage avec leurs options, validations et règles conditionnelles.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
survey_id Requis	path	UUID	UUID du sondage parent.

curl -X GET "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/questions/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"

import requests

response = requests.get(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/questions/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/questions/", {
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
console.log(await response.json());

200 OK Exemple de réponse JSON

[
  {
    "id": "8e3678fb-2917-4824-9b88-c711aa110022",
    "question_text": "Sur une échelle de 0 à 10, recommanderiez-vous notre service ?",
    "question_type": "nps",
    "type_display": "Net Promoter Score (NPS)",
    "scale_min": 0,
    "scale_max": 10,
    "scale_labels": {"0": "Pas du tout probable", "10": "Très probable"},
    "is_required": true,
    "order": 1
  }
]

03. Questions (32 Types) scope: questions:write scope: surveys:write

POST /api/surveys/manage/{survey_id}/questions/

Guide détaillé

Ajouter une question (32 types)

Ajoute une nouvelle question au sondage. Supporte les 32 types du Question Builder, la logique conditionnelle et le screening.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
survey_id Requis	path	UUID	UUID du sondage parent.
question_text Requis	body	string	Intitulé de la question.
question_type Requis	body	string	Un des 32 codes (text, textarea, email, phone, url, radio, dropdown, yesno, checkbox, multi_dropdown, tags, stars, scale, nps, likert, slider, date, datetime, time, birthdate, file, image_upload, fullname, gender, country, city, address, number, matrix_single, consent, section, description).
options	body	array<string>	Requis (min 2) pour radio, dropdown, checkbox, multi_dropdown, tags.
is_required	body	boolean	Question obligatoire (défaut : true).
is_screening	body	boolean	Question éliminatoire de screening.
disqualify_answers	body	array<string>	Réponses entraînant une disqualification immédiate.

curl -X POST "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/questions/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "question_text": "Quel moyen de paiement mobile utilisez-vous principalement ?",
    "question_type": "radio",
    "options": ["Wave", "Orange Money", "MTN MoMo", "Moov Money"],
    "is_required": true,
    "order": 1
  }'

import requests

payload = {
    "question_text": "Quel moyen de paiement mobile utilisez-vous principalement ?",
    "question_type": "radio",
    "options": ["Wave", "Orange Money", "MTN MoMo", "Moov Money"],
    "is_required": True,
    "order": 1,
}
response = requests.post(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/questions/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json=payload,
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/questions/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    question_text: "Quel moyen de paiement mobile utilisez-vous principalement ?",
    question_type: "radio",
    options: ["Wave", "Orange Money", "MTN MoMo", "Moov Money"],
    is_required: true,
    order: 1
  })
});
console.log(await response.json());

201 Created Exemple de réponse JSON

{
  "id": "8e3678fb-2917-4824-9b88-c711aa110022",
  "question_text": "Quel moyen de paiement mobile utilisez-vous principalement ?",
  "question_type": "radio",
  "type_display": "Single Choice (Radio)",
  "options": ["Wave", "Orange Money", "MTN MoMo", "Moov Money"],
  "is_required": true,
  "order": 1
}

03. Questions (32 Types) scope: questions:write scope: surveys:write

PATCH /api/surveys/manage/{survey_id}/questions/{id}/

Guide détaillé

Modifier une question

Met à jour l'intitulé, les options, l'ordre ou les règles de validation d'une question existante.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
survey_id Requis	path	UUID	UUID du sondage parent.
id Requis	path	UUID	UUID de la question.

curl -X PATCH "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/questions/8e3678fb-2917-4824-9b88-c711aa110022/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"help_text": "Sélectionnez une seule réponse."}'

import requests

response = requests.patch(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/questions/8e3678fb-2917-4824-9b88-c711aa110022/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={"help_text": "Sélectionnez une seule réponse."},
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/questions/8e3678fb-2917-4824-9b88-c711aa110022/", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ help_text: "Sélectionnez une seule réponse." })
});
console.log(await response.json());

200 OK Exemple de réponse JSON

{
  "id": "8e3678fb-2917-4824-9b88-c711aa110022",
  "question_text": "Quel moyen de paiement mobile utilisez-vous principalement ?",
  "question_type": "radio",
  "help_text": "Sélectionnez une seule réponse.",
  "order": 1
}

03. Questions (32 Types) scope: questions:write scope: surveys:write

DELETE /api/surveys/manage/{survey_id}/questions/{id}/

Guide détaillé

Supprimer une question

Supprime une question d'un sondage.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
survey_id Requis	path	UUID	UUID du sondage parent.
id Requis	path	UUID	UUID de la question.

curl -X DELETE "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/questions/8e3678fb-2917-4824-9b88-c711aa110022/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"

import requests

response = requests.delete(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/questions/8e3678fb-2917-4824-9b88-c711aa110022/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.status_code)  # 204

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/questions/8e3678fb-2917-4824-9b88-c711aa110022/", {
  method: "DELETE",
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
console.log(response.status);

204 No Content Exemple de réponse JSON

// 204 No Content

04. Éligibilité & Ciblage scope: surveys:read

GET /api/surveys/manage/{survey_id}/eligibility/

Guide détaillé

Lister les règles d'éligibilité

Retourne toutes les règles de ciblage démographique et géographique configurées sur le sondage.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
survey_id Requis	path	UUID	UUID du sondage.

curl -X GET "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/eligibility/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"

import requests

response = requests.get(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/eligibility/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/eligibility/", {
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
console.log(await response.json());

200 OK Exemple de réponse JSON

[
  {
    "id": "c41901a2-7b12-4d99-81b2-990122334455",
    "rule_type": "country",
    "rule_type_display": "Country",
    "operator": "in",
    "operator_display": "In",
    "value": ["CI", "SN", "FR"]
  }
]

04. Éligibilité & Ciblage scope: surveys:write

POST /api/surveys/manage/{survey_id}/eligibility/

Guide détaillé

Ajouter une règle d'éligibilité

Ajoute un filtre de ciblage (age_min, age_max, country, city, gender, has_skill, level) avec opérateur (eq, ne, gt, lt, in, not_in).

Paramètres de la requête

Paramètre	Emplacement	Type	Description
survey_id Requis	path	UUID	UUID du sondage.
rule_type Requis	body	string	age_min, age_max, country, city, gender, has_skill ou level.
operator Requis	body	string	eq, ne, gt, lt, in ou not_in.
value Requis	body	JSON	Valeur attendue (nombre, chaîne ou liste).

curl -X POST "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/eligibility/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "country",
    "operator": "in",
    "value": ["CI", "SN", "FR"]
  }'

import requests

response = requests.post(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/eligibility/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "rule_type": "country",
        "operator": "in",
        "value": ["CI", "SN", "FR"],
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/eligibility/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    rule_type: "country",
    operator: "in",
    value: ["CI", "SN", "FR"]
  })
});
console.log(await response.json());

201 Created Exemple de réponse JSON

{
  "id": "c41901a2-7b12-4d99-81b2-990122334455",
  "rule_type": "country",
  "rule_type_display": "Country",
  "operator": "in",
  "operator_display": "In",
  "value": ["CI", "SN", "FR"]
}

05. Réponses & Participation scope: responses:read

GET /api/surveys/manage/{survey_id}/responses/

Guide détaillé

Lister les réponses collectées

Retourne les sessions de réponses d'un sondage avec statut, durée, quality_score et réponses détaillées.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
survey_id Requis	path	UUID	UUID du sondage.
status	query	string	Filtrer par statut : started, completed, abandoned, disqualified.

curl -X GET "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/responses/?status=completed" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"

import requests

response = requests.get(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/responses/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    params={"status": "completed"},
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/responses/?status=completed", {
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
console.log(await response.json());

200 OK Exemple de réponse JSON

{
  "count": 1,
  "results": [
    {
      "id": "e9b5a882-9477-44c0-9989-11f4d9c7e112",
      "user_full_name": "Anonyme",
      "status": "completed",
      "time_spent": 142,
      "quality_score": "0.92",
      "answers": [
        {
          "question": "8e3678fb-2917-4824-9b88-c711aa110022",
          "question_text": "Quel moyen de paiement mobile utilisez-vous principalement ?",
          "question_type": "radio",
          "question_order": 1,
          "answer": "Wave"
        }
      ]
    }
  ]
}

05. Réponses & Participation scope: surveys:read

POST /api/surveys/{id}/start/

Guide détaillé

Démarrer une session de réponse

Démarre une session de participation authentifiée (statut started) après vérification d'éligibilité.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
id Requis	path	UUID	UUID du sondage actif.

curl -X POST "https://docs.ekenno.com/api/surveys/368de50f-5df6-4b15-b6cf-f5ff6d123c90/start/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"

import requests

response = requests.post(
    "https://docs.ekenno.com/api/surveys/368de50f-5df6-4b15-b6cf-f5ff6d123c90/start/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/368de50f-5df6-4b15-b6cf-f5ff6d123c90/start/", {
  method: "POST",
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
console.log(await response.json());

201 Created Exemple de réponse JSON

{
  "id": "e9b5a882-9477-44c0-9989-11f4d9c7e112",
  "survey": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
  "status": "started",
  "started_at": "2026-11-12T16:10:00Z"
}

05. Réponses & Participation scope: surveys:write

POST /api/surveys/{id}/submit/

Guide détaillé

Soumettre les réponses d'un sondage

Valide et enregistre toutes les réponses d'une session active, calcule le quality_score et crédite la récompense KEN.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
id Requis	path	UUID	UUID du sondage.
answers Requis	body	array<object>	Liste d'objets {question_id, answer}.

curl -X POST "https://docs.ekenno.com/api/surveys/368de50f-5df6-4b15-b6cf-f5ff6d123c90/submit/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": [
      {
        "question_id": "8e3678fb-2917-4824-9b88-c711aa110022",
        "answer": "Wave"
      }
    ]
  }'

import requests

response = requests.post(
    "https://docs.ekenno.com/api/surveys/368de50f-5df6-4b15-b6cf-f5ff6d123c90/submit/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "answers": [
            {"question_id": "8e3678fb-2917-4824-9b88-c711aa110022", "answer": "Wave"}
        ]
    },
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/368de50f-5df6-4b15-b6cf-f5ff6d123c90/submit/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    answers: [
      { question_id: "8e3678fb-2917-4824-9b88-c711aa110022", answer: "Wave" }
    ]
  })
});
console.log(await response.json());

200 OK Exemple de réponse JSON

{
  "message": "Survey completed successfully.",
  "response": {
    "id": "e9b5a882-9477-44c0-9989-11f4d9c7e112",
    "status": "completed",
    "time_spent": 94,
    "quality_score": "0.88"
  }
}

06. Analytics & Exports scope: analytics:read scope: responses:read

GET /api/surveys/manage/{id}/results/

Guide détaillé

Résultats analytiques agrégés

Calcule les métriques globales (taux de complétion, durée moyenne, score global) et les statistiques par question (distributions de choix, moyenne, médiane, NPS).

Paramètres de la requête

Paramètre	Emplacement	Type	Description
id Requis	path	UUID	UUID du sondage.

curl -X GET "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/results/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"

import requests

response = requests.get(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/results/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/results/", {
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
const analytics = await response.json();
console.log(analytics);

200 OK Exemple de réponse JSON

{
  "survey_id": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
  "survey_title": "Baromètre Expérience Client Q4",
  "total_responses": 142,
  "total_started": 160,
  "completed_count": 142,
  "completion_rate": 88.8,
  "avg_time_seconds": 185,
  "avg_time_formatted": "3m 5s",
  "overall_avg_score": 4.6,
  "questions": [
    {
      "question_id": "8e3678fb-2917-4824-9b88-c711aa110022",
      "order": 1,
      "analytics_type": "choice",
      "answer_count": 142,
      "choice_stats": [
        {"label": "Wave", "count": 88, "percentage": 62.0},
        {"label": "Orange Money", "count": 54, "percentage": 38.0}
      ]
    }
  ]
}

06. Analytics & Exports scope: export:read scope: responses:read

GET /api/surveys/manage/{survey_id}/export/

Guide détaillé

Exporter les réponses (CSV / JSON)

Télécharge l'intégralité des réponses d'un sondage au format CSV tabulaire (défaut) ou JSON structuré (?format=json).

Paramètres de la requête

Paramètre	Emplacement	Type	Description
survey_id Requis	path	UUID	UUID du sondage.
format	query	string	csv (défaut) ou json.

curl -X GET "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/export/?format=json" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -o export_responses.json

import requests

response = requests.get(
    "https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/export/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    params={"format": "json"},
    timeout=15,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/surveys/manage/368de50f-5df6-4b15-b6cf-f5ff6d123c90/export/?format=json", {
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
const exportPayload = await response.json();
console.log(exportPayload);

200 OK Exemple de réponse JSON

{
  "survey_id": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
  "survey_title": "Baromètre Expérience Client Q4",
  "total_responses": 142,
  "exported_at": "2026-11-12T16:15:00Z",
  "responses": []
}

07. Webhooks & Événements scope: surveys:write

POST /api/developer/webhooks/

Guide détaillé

Enregistrer un endpoint Webhook

Configure un abonnement HTTP POST signé par HMAC-SHA256 pour les événements on_start, on_complete et on_abandon.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
url Requis	body	URL	URL HTTPS réceptrice de votre serveur.
survey_id	body	UUID	UUID du sondage cible.
on_start	body	boolean	Notifier au démarrage d'une réponse.
on_complete	body	boolean	Notifier à la validation finale (défaut : true).
on_abandon	body	boolean	Notifier en cas d'abandon ou disqualification.

curl -X POST "https://docs.ekenno.com/api/developer/webhooks/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.votre-domaine.com/webhooks/ekenno",
    "survey_id": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
    "on_complete": true,
    "on_abandon": true
  }'

import requests

response = requests.post(
    "https://docs.ekenno.com/api/developer/webhooks/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "url": "https://api.votre-domaine.com/webhooks/ekenno",
        "survey_id": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
        "on_complete": True,
        "on_abandon": True,
    },
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/developer/webhooks/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://api.votre-domaine.com/webhooks/ekenno",
    survey_id: "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
    on_complete: true,
    on_abandon: true
  })
});
console.log(await response.json());

201 Created Exemple de réponse JSON

{
  "message": "Webhook endpoint created successfully.",
  "webhook": {
    "id": "a91bc220-1122-4334-9988-776655443322",
    "survey_id": "368de50f-5df6-4b15-b6cf-f5ff6d123c90",
    "url": "https://api.votre-domaine.com/webhooks/ekenno",
    "secret_key": "whsec_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
    "events": ["on_complete", "on_abandon"],
    "is_active": true
  }
}

08. Clés d'API (Developer) Session ou Bearer Token

GET /api/developer/keys/

Guide détaillé

Lister vos clés d'API

Retourne toutes les clés d'API de votre workspace avec leur préfixe masqué, leur environnement (live/test), leurs scopes et leur dernier horodatage d'utilisation.

Cet endpoint ne requiert aucun paramètre de corps ou de query obligatoire.

curl -X GET "https://docs.ekenno.com/api/developer/keys/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"

import requests

response = requests.get(
    "https://docs.ekenno.com/api/developer/keys/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/developer/keys/", {
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
console.log(await response.json());

200 OK Exemple de réponse JSON

{
  "count": 1,
  "results": [
    {
      "id": "d1234567-89ab-4cde-9012-3456789abcde",
      "name": "Default Production Key",
      "mode": "live",
      "key_prefix": "ek_live_...fe8b",
      "scopes": ["surveys:read", "surveys:write", "questions:write", "responses:read"],
      "is_active": true,
      "rate_limit": 1000
    }
  ]
}

08. Clés d'API (Developer) Session ou Bearer Token

POST /api/developer/keys/

Guide détaillé

Générer une nouvelle clé d'API

Crée une nouvelle clé Live ou Test avec des scopes précis. Le secret complet raw_key n'est retourné qu'une seule fois dans cette réponse 201.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
name Requis	body	string	Nom descriptif de la clé.
mode	body	string	live (défaut) ou test.
scopes	body	array<string>	Liste des scopes accordés.

curl -X POST "https://docs.ekenno.com/api/developer/keys/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Backend Service",
    "mode": "live",
    "scopes": ["surveys:read", "surveys:write", "questions:write", "responses:read"]
  }'

import requests

response = requests.post(
    "https://docs.ekenno.com/api/developer/keys/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "name": "CI/CD Backend Service",
        "mode": "live",
        "scopes": ["surveys:read", "surveys:write", "questions:write", "responses:read"],
    },
    timeout=10,
)
print(response.json()["api_key"]["raw_key"])

const response = await fetch("https://docs.ekenno.com/api/developer/keys/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "CI/CD Backend Service",
    mode: "live",
    scopes: ["surveys:read", "surveys:write", "questions:write", "responses:read"]
  })
});
const data = await response.json();
console.log("Save secret once:", data.api_key.raw_key);

201 Created Exemple de réponse JSON

{
  "message": "API key created. Please save this secret key now, it cannot be displayed again.",
  "api_key": {
    "id": "d1234567-89ab-4cde-9012-3456789abcde",
    "name": "CI/CD Backend Service",
    "mode": "live",
    "key_prefix": "ek_live_...9a1b",
    "raw_key": "ek_live_48_hex_characters_secret_shown_only_once_9a1b",
    "scopes": ["surveys:read", "surveys:write", "questions:write", "responses:read"],
    "is_active": true
  }
}

08. Clés d'API (Developer) Session ou Bearer Token

POST /api/developer/keys/{id}/roll/

Guide détaillé

Rotation (Roll) d'une clé d'API

Invalide immédiatement l'ancien secret et génère un nouveau secret raw_key tout en conservant l'ID et les scopes de la clé.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
id Requis	path	UUID	UUID de la clé à régénérer.

curl -X POST "https://docs.ekenno.com/api/developer/keys/d1234567-89ab-4cde-9012-3456789abcde/roll/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"

import requests

response = requests.post(
    "https://docs.ekenno.com/api/developer/keys/d1234567-89ab-4cde-9012-3456789abcde/roll/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.json()["api_key"]["raw_key"])

const response = await fetch("https://docs.ekenno.com/api/developer/keys/d1234567-89ab-4cde-9012-3456789abcde/roll/", {
  method: "POST",
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
console.log(await response.json());

200 OK Exemple de réponse JSON

{
  "message": "API key regenerated. Please copy and store your new key now.",
  "api_key": {
    "id": "d1234567-89ab-4cde-9012-3456789abcde",
    "key_prefix": "ek_live_...c4d2",
    "raw_key": "ek_live_new_rotated_secret_token_c4d2",
    "is_active": true
  }
}

08. Clés d'API (Developer) Session ou Bearer Token

DELETE /api/developer/keys/{id}/

Guide détaillé

Révoquer une clé d'API

Désactive définitivement une clé d'API (is_active = false). Toute requête ultérieure avec ce jeton recevra 401 Unauthorized.

Paramètres de la requête

Paramètre	Emplacement	Type	Description
id Requis	path	UUID	UUID de la clé à révoquer.

curl -X DELETE "https://docs.ekenno.com/api/developer/keys/d1234567-89ab-4cde-9012-3456789abcde/" \
  -H "Authorization: Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"

import requests

response = requests.delete(
    "https://docs.ekenno.com/api/developer/keys/d1234567-89ab-4cde-9012-3456789abcde/",
    headers={"Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=10,
)
print(response.json())

const response = await fetch("https://docs.ekenno.com/api/developer/keys/d1234567-89ab-4cde-9012-3456789abcde/", {
  method: "DELETE",
  headers: { "Authorization": "Bearer ek_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
});
console.log(await response.json());

200 OK Exemple de réponse JSON

{
  "message": "API key revoked successfully.",
  "id": "d1234567-89ab-4cde-9012-3456789abcde",
  "is_active": false
}

Référence Technique des Endpoints REST

Lister les catégories actives

Lister vos sondages

Paramètres de la requête

Créer un nouveau sondage

Paramètres de la requête

Récupérer les détails d'un sondage

Paramètres de la requête

Mettre à jour un sondage

Paramètres de la requête

Publier un sondage

Paramètres de la requête

Mettre un sondage en pause

Paramètres de la requête

Clôturer définitivement un sondage

Paramètres de la requête

Supprimer un sondage

Paramètres de la requête

Lister les questions d'un sondage

Paramètres de la requête

Ajouter une question (32 types)

Paramètres de la requête

Modifier une question

Paramètres de la requête

Supprimer une question

Paramètres de la requête

Lister les règles d'éligibilité

Paramètres de la requête

Ajouter une règle d'éligibilité

Paramètres de la requête

Lister les réponses collectées

Paramètres de la requête

Démarrer une session de réponse

Paramètres de la requête

Soumettre les réponses d'un sondage

Paramètres de la requête

Résultats analytiques agrégés

Paramètres de la requête

Exporter les réponses (CSV / JSON)

Paramètres de la requête

Enregistrer un endpoint Webhook

Paramètres de la requête

Lister vos clés d'API

Générer une nouvelle clé d'API

Paramètres de la requête

Rotation (Roll) d'une clé d'API

Paramètres de la requête

Révoquer une clé d'API

Paramètres de la requête