Documentation de l’API

API Sondora, version 1

Une API REST en JSON. Adresse de base : https://sondora.fr/api/v1

Authentification

Un administrateur crée les clés dans l'espace client, rubrique API et webhooks. Chaque clé porte ses propres droits et se révoque à tout moment. Transmettez-la dans l'en-tête Authorization. Ne la placez jamais dans une page web ni dans une application mobile.

curl https://sondora.fr/api/v1/campaigns \
  -H "Authorization: Bearer sk_sondora_…"

Limite : 120 requêtes par minute et par clé. Au-delà, l'API répond 429.

Provenance des contacts

Tout envoi de contacts doit indiquer d'où vient le fichier : source (texte libre), legal_basis (consentement, interet_legitime, contrat, mission_interet_public ou obligation_legale) et collected_on (date de collecte, AAAA-MM-JJ). Si l'un des trois manque, le lot entier est refusé. Vous restez responsable de la licéité de vos fichiers.

Points d'accès

GET/surveysdroit campaigns:read

Liste vos enquêtes, pour récupérer l’identifiant à utiliser lors de la création d’une campagne.

GET/campaignsdroit campaigns:read

Liste vos campagnes avec leur statut et leurs compteurs.

POST/campaignsdroit campaigns:write

Crée une campagne à partir d’une enquête.

{ "survey_id": "…", "name": "Satisfaction novembre", "target_completes": 200 }

GET/campaigns/{id}droit campaigns:read

Statut d’une campagne : contacts par statut, appels passés, entretiens complets.

PATCH/campaigns/{id}droit campaigns:write

Change le statut : prete (prête à lancer), brouillon, en_pause, terminee.

{ "status": "prete" }

POST/campaigns/{id}/contactsdroit contacts:write

Ajoute de 1 à 1 000 contacts. Les numéros français sont acceptés au format national ou international. Les numéros de votre liste d’opposition sont écartés.

{
  "source": "Clients ayant acheté en octobre",
  "legal_basis": "interet_legitime",
  "collected_on": "2026-10-31",
  "contacts": [
    { "phone": "06 12 34 56 78", "first_name": "Camille", "attrs": { "agence": "Lyon" } }
  ]
}

GET/campaigns/{id}/resultsdroit results:read

Résultats par contact appelé : statut, dernier appel, réponses codées. Paramètres : limit (200 au plus), cursor (valeur next_cursor de la page précédente), transcript=true pour joindre la transcription.

Envoi d'un fichier CSV : même adresse que l'ajout de contacts, avec l'en-tête Content-Type: text/csv, une colonne phone ou telephone, et les trois champs de provenance en paramètres d'URL. Les autres colonnes deviennent des attributs du contact, utilisables comme axes d'analyse.

Erreurs

Une erreur renvoie un code HTTP et un corps { "error": { "code": "…", "message": "…" } }. Codes courants : 401 clé invalide ou révoquée, 403 droit insuffisant, 404 ressource introuvable, 409 opération impossible dans l'état de la campagne, 422 saisie invalide, 429 limite de débit.

Webhooks

Déclarez une adresse HTTPS dans l'espace client et choisissez les événements : appel.termine, enquete.completee, contact.injoignable, opposition.exprimee, campagne.terminee. Chaque notification est un POST en JSON avec l'en-tête Sondora-Signature. Répondez par un code 2xx en moins de 5 secondes. Le bouton « Envoyer un essai » de l'espace client vous permet de vérifier votre branchement.

// Node.js : vérifier la signature d'une notification
import { createHmac, timingSafeEqual } from 'node:crypto';

function verifier(corpsBrut, enTete, secret) {
  const { t, v1 } = Object.fromEntries(enTete.split(',').map(p => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;   // rejette une notification rejouée
  const attendu = createHmac('sha256', secret).update(t + '.' + corpsBrut).digest('hex');
  return attendu.length === v1.length && timingSafeEqual(Buffer.from(attendu), Buffer.from(v1));
}

Statuts

Campagne : brouillon, prete, en_cours, en_pause, terminee. Contact : a_appeler, rappel, complete, partiel, refus, injoignable, faux_numero, hors_cible, opposition.