Créez d’abord une clé depuis Paramètres > Intégrations > API Ubic. La clé est liée à votre espace de travail et ne doit jamais être intégrée dans une application accessible depuis un navigateur.
L’adresse de base est https://app.getubic.com/api/partner/v1.
Ajoutez la clé à chaque requête avec l’en-tête Authorization: Bearer VOTRE_CLE_API. Pour les requêtes avec un corps JSON, ajoutez également Content-Type: application/json.
Une clé remplacée ou désactivée cesse immédiatement de fonctionner. Toutes les données renvoyées restent limitées à l’espace de travail associé à la clé.
Créez une session avec POST /sessions. Le corps doit contenir :
name : nom de la session ;
owner_email : e-mail d’un utilisateur membre de l’espace de travail ;
contacts : de 1 à 200 contacts, chacun avec au minimum phone ;
external_reference ou l’en-tête Idempotency-Key pour éviter de créer deux fois la même session ;
en option, metadata et les informations du contact : external_id, first_name, last_name, email, company, job_title et custom_fields.
Par exemple, une session peut utiliser Campagne juillet comme name, l’e-mail de l’agent comme owner_email et campaign-2026-07 comme external_reference. Chaque objet de contacts contient alors le téléphone et les informations disponibles sur le prospect.
La réponse contient notamment l’identifiant id de la session et open_url, l’adresse que l’agent peut ouvrir dans Ubic pour lancer les appels. L’API prépare la session, mais ne démarre, ne contrôle et ne termine jamais les appels à la place de l’agent connecté.
Utilisez ensuite :
GET /sessions pour lister les sessions, avec created_since, page et per_page ;
GET /sessions/{id}/contacts pour récupérer les contacts d’une session ;
GET /sessions/{id}/calls pour récupérer les appels réellement lancés, avec since, page et per_page.
created_since et since acceptent une date ISO 8601 avec fuseau horaire. La pagination contient page, per_page et total. La taille d’une page est de 50 éléments par défaut et de 100 au maximum. Les filtres de date sont inclusifs : dédupliquez les résultats avec leur champ id.
Les contacts renvoient leur identité, leur société, leur téléphone, leur e-mail, leur note, leurs champs personnalisés, leur statut d’appel et leur qualification actuelle. Les appels ajoutent les dates, la durée, l’agent, le sens de l’appel et le résultat enregistré au moment de la qualification.
Les statuts techniques d’un appel sont : queued, sent, received, delivered, initiated, ringing, in-progress, completed, failed, busy, no-answer et canceled.
Les statuts d’appel d’un contact sont : not_started, ringing, connected, completed, deferred et failed. Les qualifications métier et leurs libellés dépendent des statuts configurés dans l’espace de travail. Un rendez-vous est identifié par is_conversion et peut être complété par des champs personnalisés, par exemple pour sa date ou son identifiant externe.
Ajoutez include_transcriptions=true pour demander la transcription et include_recordings=true pour obtenir les métadonnées d'enregistrement. L'API ne renvoie pas l'URL du fichier audio.
Une clé autorisée à lire les tâches peut utiliser :
GET /tasks pour lister les tâches de l'espace de travail, avec updated_since, cursor et per_page ;
GET /tasks/{id} pour récupérer une tâche précise.
updated_since accepte une date ISO 8601 avec fuseau horaire. Pour charger la suite, renvoyez la valeur pagination.next_cursor dans le paramètre cursor, jusqu’à ce que cette valeur soit vide. Le curseur conserve automatiquement le filtre de départ. Une tâche modifiée pendant la lecture peut réapparaître ; utilisez son id pour la dédupliquer.
Chaque tâche contient son identifiant, son statut, son type, sa note, son échéance, ses dates de création et de mise à jour, son agent assigné et les informations principales du prospect associé.
Pour créer une tâche, utilisez POST /tasks avec :
lead_id : identifiant Ubic du prospect ;
due_at : date et heure d'échéance au format ISO 8601 avec fuseau horaire ;
external_reference ou l’en-tête Idempotency-Key pour éviter de créer deux fois la même tâche ;
en option, assignee_email, type et note.
Le prospect et l'agent assigné doivent appartenir à l'espace de travail de la clé. Sans assignee_email, Ubic assigne la tâche au propriétaire de la liste du prospect. Si aucun agent ne peut être déterminé, la requête est refusée.
Le type doit correspondre à une valeur configurée dans l'espace de travail. Quand il est absent, Ubic utilise le type de tâche par défaut. Si la même référence est rejouée après une coupure réseau, Ubic renvoie la tâche existante sans créer de doublon.
La lecture demande le droit tasks:read et la création le droit tasks:write. Cette première version de l'API permet de lister, lire et créer des tâches ; leur modification et leur suppression restent disponibles dans Ubic.
Si votre clé a été créée avant l'ajout des tâches à l'API, remplacez-la depuis Paramètres > Intégrations > API Ubic pour lui attribuer ces droits.
Création de sessions ou de tâches : 30 requêtes par minute, par clé API et par adresse IP.
Lecture des sessions, contacts, appels et tâches : 120 requêtes par minute, par clé API et par adresse IP.
En cas de dépassement, l’API répond avec le code 429 et l’en-tête Retry-After. Attendez le nombre de secondes indiqué avant de réessayer.
Les principaux autres codes sont 400 pour un JSON invalide, 401 pour une clé absente ou invalide, 403 pour un droit manquant, 404 pour une ressource introuvable, 409 pour un conflit d’idempotence et 422 pour une donnée ou un paramètre invalide.
Le contrat complet, les modèles de réponse et les champs disponibles sont également consultables dans la documentation développeur de l’API partenaire Ubic.
