API

Développez avec l’API Perbene

API REST pour gérer les contacts, les demandes de service, les techniciens, la planification, les appels, les messages, les prospects et votre base de connaissances, depuis des agents externes, des intégrations ou vos propres automatisations.

01 / Authentication

Démarrez en 3 étapes

Obtenir une clé API
  1. 01

    Émettez une clé API

    Allez dans Paramètres du profil → Clés API et cliquez sur Générer une clé. Copiez-la immédiatement. Elle n’est affichée qu’à la création.

  2. 02

    Définissez la variable d’environnement

    export PERBENE_API_KEY=pbn_live_…

  3. 03

    Appelez l’API

    Envoyez X-API-Key à chaque requête vers https://api.perbene.ai. Votre clé est liée à votre organisation.

02 / First request

curl

Listez les contacts de votre espace.

bash
curl https://api.perbene.ai/api/contacts \
  -H "X-API-Key: pbn_live_xxxxxxxxxxxx"

Python

Un client prêt à l’emploi utilisant httpx.

python
import os
import httpx

PERBENE_API_KEY = os.environ["PERBENE_API_KEY"]
BASE_URL = "https://api.perbene.ai"

client = httpx.Client(
    base_url=BASE_URL,
    headers={"X-API-Key": PERBENE_API_KEY, "User-Agent": "perbene/1.0"},
    timeout=30.0,
)

# List your contacts
contacts = client.get("/api/contacts").json()

# Create a service request
client.post("/api/service-requests", json={
    "address": "123 Main St",
    "category": "plumbing",
    "description": "Leaking sink",
    "priority": "MEDIUM",
})

# Make an outbound call to a known contact
client.post("/api/campaigns/entity-call", json={
    "contact_id": contacts["items"][0]["id"],
    "agent_prompt": "Hi, calling to confirm tomorrow's 2pm appointment.",
})

03 / Surface area

Points de terminaison

Les points de terminaison les plus utiles pour les agents et les intégrations. Pour les schémas complets de requête/réponse, consultez la spécification OpenAPI en direct.

Contacts

  • GET/api/contactsLister avec recherche et pagination
  • GET/api/contacts/searchRecherche légère
  • POST/api/contactsCréer un contact
  • PUT/api/contacts/{id}Mettre à jour

Prospects

  • GET/api/leadsLister les prospects qualifiés
  • POST/api/leadsCréer un prospect
  • PUT/api/leads/{id}Mettre à jour

Demandes de service

  • GET/api/service-requestsLister les travaux / bons de commande
  • POST/api/service-requestsEn créer une
  • PUT/api/service-requests/{id}Mettre à jour le statut, les notes
  • POST/api/service-requests/{id}/quoteJoindre un devis
  • POST/api/service-requests/{id}/emergencyEscalader en urgent
  • GET/api/quotes/pendingListe des devis en attente
  • GET/api/emergencies/activeDemandes urgentes actives

Offres de service & prestataires

  • GET/api/service-listingsCatalogue des services proposés
  • POST/api/service-listingsAjouter une offre
  • GET/api/service-providersPrestataires externes
  • POST/api/service-providersAjouter un prestataire

Techniciens & répartition

  • GET/api/techniciansLister les techniciens
  • POST/api/techniciansAjouter un technicien
  • GET/api/technicians/on-call/currentQui est de garde maintenant
  • GET/api/technicians/on-call/scheduleRotation des gardes
  • POST/api/technicians/dispatchAffecter un technicien à un travail
  • GET/api/technicians/dispatch/activeAffectations actives
  • PUT/api/technicians/dispatch/{id}Mettre à jour le statut / l’heure d’arrivée

Planification (rendez-vous)

  • GET/api/scheduling/typesLister les types de rendez-vous
  • POST/api/scheduling/check-availabilityTrouver des créneaux disponibles
  • POST/api/scheduling/bookRéserver un créneau pour un contact
  • POST/api/scheduling/manageReprogrammer ou annuler
  • GET/api/scheduling/appointmentsLister les réservations

Campagnes sortantes

  • POST/api/campaigns/quick-callAppel ponctuel vers un numéro de téléphone
  • POST/api/campaigns/entity-callAppel ponctuel vers un contact / prospect connu
  • POST/api/campaignsCréer une campagne multi-contacts
  • POST/api/campaigns/{id}/contacts/uploadImport CSV
  • POST/api/campaigns/{id}/startLancer / reprendre
  • POST/api/campaigns/{id}/pauseMettre en pause
  • GET/api/campaigns/{id}/contactsStatut & dispositions par contact

Appels, messages, conversations

  • GET/api/callsLister les enregistrements d’appels
  • GET/api/calls/{id}Détail avec transcription
  • GET/api/calls/{id}/recordingURL de l’enregistrement
  • GET/api/messagesMessages SMS
  • GET/api/conversationsFils multicanaux
  • POST/api/conversations/{id}/messagesAjouter un message

Base de connaissances & RAG

  • GET/api/knowledge-base/sourcesLister les sources
  • POST/api/knowledge-base/sourcesAjouter une source (URL ou texte)
  • POST/api/knowledge-base/sources/uploadTéléverser un fichier
  • POST/api/knowledge-base/searchRecherche RAG utilisée par l’agent

Alertes urgentes, dispositions, DNC

  • GET/api/urgent-alertsLister les alertes urgentes
  • POST/api/urgent-alertsEn créer une
  • GET/api/dispositionsCatégories de résultats d’appel
  • GET/api/dncListe de numéros à ne pas appeler
  • GET/api/dnc/check/{phone}Vérifier un numéro
  • POST/api/dnc/bulkImport en masse

Statistiques & activité

  • GET/api/statistics/dashboardCompteurs principaux
  • GET/api/statistics/metrics/time-seriesMétriques dans le temps
  • GET/api/statistics/service-requests/by-statusHistogramme des statuts
  • GET/api/activitiesActivité récente de l’agent

04 / Resilience

Erreurs & modèles

401

Clé manquante, révoquée ou expirée. Réémettez-la depuis le tableau de bord.

403

Le point de terminaison requiert un rôle supérieur. Vous ne devriez pas voir cela avec une clé API normale.

404

La ressource n’existe pas ou appartient à un autre espace.

422

Échec de la validation. Le corps contient la raison au niveau du champ.

429

Débit limité. Patientez et réessayez.

5xx

Transitoire. Réessayez avec un délai exponentiel.

Pagination. Les points de terminaison de liste acceptent ?page=1&page_size=50 et renvoient { items: [...], total: N }.

Recherche. Là où c’est pris en charge, ?search=… effectue une correspondance insensible à la casse.

Identifiants. Les ressources utilisent des UUID. Traitez-les comme des chaînes opaques.

Isolation des espaces. Votre clé est liée à une seule organisation ; l’en-tête X-Organization-Id est ignoré.

Prêt à développer ?

Émettez une clé depuis votre tableau de bord et commencez à envoyer des requêtes en quelques minutes.

Obtenir une clé API
Essai gratuit