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.
Pour récupérer tout l’historique d’une période, utilisez GET /calls avec les paramètres obligatoires started_from inclusif et started_until exclusif. La plage est limitée à 31 jours et demande le droit workspace_calls:read. Chaque appel contient aussi list avec l’identifiant Ubic stable, le nom actuel et, lorsqu’elle existe, la référence externe de sa liste d’origine. list vaut null si cette liste n’existe plus.
Pour lire aussi les appels sans contact identifiable, utilisez GET /api/partner/v2/calls avec la même clé, les mêmes droits et les mêmes paramètres. Cette réponse ajoute caller_identity ; lead et list valent null pour un appel non identifié. Utilisez l’id de l’appel pour le suivre, sans créer de prospect artificiel. V1 conserve ses réponses historiques tant qu’un prospect reste lié à l’appel ; si une page contient un appel sans prospect, elle répond 409 api_version_required et doit être lue en V2. Les autres routes restent en V1.
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 (`type_id` et libellé), sa note, son échéance, ses dates de création et de mise à jour, son agent assigné et les informations principales du prospect associé. `type_id` vaut `null` si le type a été supprimé des paramètres de l'espace.
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_id 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.
Une tâche doit concerner un vrai contact. Une ancienne fiche commune à des appelants masqués est refusée avec 422 identified_contact_required ; un contact identifié sans téléphone reste utilisable.
Pour trouver le bon identifiant, appelez GET /task-types avec une clé ayant le droit tasks:write. La réponse donne l'id, la valeur technique, le libellé et le type par défaut de chaque type configuré dans l'espace. Envoyez cet id dans type_id (par exemple `"type_id": 2`) ; Make peut aussi envoyer une chaîne de chiffres. Un libellé comme `No-show` ne doit pas être envoyé dans ce champ.
L'ancien champ type accepte toujours la valeur technique pour les intégrations existantes. N'envoyez pas type et type_id ensemble. Quand les deux sont absents, Ubic utilise le type de tâche par défaut. Gardez le même champ et la même valeur lors d'un rejeu avec la même référence. 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 ou une lecture nécessitant V2, 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.
