API

Crea con la API de Perbene

API REST para gestionar contactos, solicitudes de servicio, técnicos, programación, llamadas, mensajes, leads y tu base de conocimiento, desde agentes externos, integraciones o tus propias automatizaciones.

01 / Authentication

Empieza en 3 pasos

Obtener una clave API
  1. 01

    Emite una clave API

    Ve a Ajustes del perfil → Claves API y haz clic en Generar clave. Cópiala una vez. Solo se muestra al crearla.

  2. 02

    Define la variable de entorno

    export PERBENE_API_KEY=pbn_live_…

  3. 03

    Llama a la API

    Envía X-API-Key en cada solicitud a https://api.perbene.ai. Tu clave está vinculada a tu organización.

02 / First request

curl

Lista los contactos de tu espacio.

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

Python

Un cliente listo para usar con 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

Endpoints

Los endpoints más útiles para agentes e integraciones. Para los esquemas completos de solicitud/respuesta consulta la especificación OpenAPI en vivo.

Contactos

  • GET/api/contactsListar con búsqueda y paginación
  • GET/api/contacts/searchBúsqueda ligera
  • POST/api/contactsCrear un contacto
  • PUT/api/contacts/{id}Actualizar

Leads

  • GET/api/leadsListar leads cualificados
  • POST/api/leadsCrear un lead
  • PUT/api/leads/{id}Actualizar

Solicitudes de servicio

  • GET/api/service-requestsListar trabajos / órdenes de trabajo
  • POST/api/service-requestsCrear una
  • PUT/api/service-requests/{id}Actualizar estado, notas
  • POST/api/service-requests/{id}/quoteAdjuntar un presupuesto
  • POST/api/service-requests/{id}/emergencyEscalar a urgente
  • GET/api/quotes/pendingLista de presupuestos pendientes
  • GET/api/emergencies/activeSolicitudes urgentes activas

Listados de servicios & proveedores

  • GET/api/service-listingsCatálogo de servicios ofrecidos
  • POST/api/service-listingsAñadir un listado
  • GET/api/service-providersProveedores externos
  • POST/api/service-providersAñadir un proveedor

Técnicos & despacho

  • GET/api/techniciansListar técnicos
  • POST/api/techniciansAñadir un técnico
  • GET/api/technicians/on-call/currentQuién está de guardia ahora
  • GET/api/technicians/on-call/scheduleRotación de guardias
  • POST/api/technicians/dispatchDespachar un técnico a un trabajo
  • GET/api/technicians/dispatch/activeDespachos activos
  • PUT/api/technicians/dispatch/{id}Actualizar estado / hora estimada

Programación (citas)

  • GET/api/scheduling/typesListar tipos de cita
  • POST/api/scheduling/check-availabilityBuscar huecos disponibles
  • POST/api/scheduling/bookReservar un hueco para un contacto
  • POST/api/scheduling/manageReprogramar o cancelar
  • GET/api/scheduling/appointmentsListar reservas

Campañas salientes

  • POST/api/campaigns/quick-callLlamada puntual a un número de teléfono
  • POST/api/campaigns/entity-callLlamada puntual a un contacto / lead conocido
  • POST/api/campaignsCrear una campaña multicontacto
  • POST/api/campaigns/{id}/contacts/uploadCarga CSV
  • POST/api/campaigns/{id}/startLanzar / reanudar
  • POST/api/campaigns/{id}/pausePausar
  • GET/api/campaigns/{id}/contactsEstado & disposiciones por contacto

Llamadas, mensajes, conversaciones

  • GET/api/callsListar registros de llamadas
  • GET/api/calls/{id}Detalle con transcripción
  • GET/api/calls/{id}/recordingURL de la grabación
  • GET/api/messagesMensajes SMS
  • GET/api/conversationsHilos multicanal
  • POST/api/conversations/{id}/messagesAñadir un mensaje

Base de conocimiento & RAG

  • GET/api/knowledge-base/sourcesListar fuentes
  • POST/api/knowledge-base/sourcesAñadir una fuente (URL o texto)
  • POST/api/knowledge-base/sources/uploadSubir un archivo
  • POST/api/knowledge-base/searchBúsqueda RAG que usa el agente

Alertas urgentes, disposiciones, DNC

  • GET/api/urgent-alertsListar alertas urgentes
  • POST/api/urgent-alertsCrear una
  • GET/api/dispositionsCategorías de resultado de llamada
  • GET/api/dncLista de no llamar
  • GET/api/dnc/check/{phone}Comprobar un teléfono
  • POST/api/dnc/bulkCarga masiva

Estadísticas & actividad

  • GET/api/statistics/dashboardContadores principales
  • GET/api/statistics/metrics/time-seriesMétricas a lo largo del tiempo
  • GET/api/statistics/service-requests/by-statusHistograma de estados
  • GET/api/activitiesActividad reciente del agente

04 / Resilience

Errores & patrones

401

Clave ausente, revocada o caducada. Vuelve a emitirla desde el panel.

403

El endpoint requiere un rol superior. No deberías ver esto con una clave API normal.

404

El recurso no existe o pertenece a otro espacio.

422

Falló la validación. El cuerpo contiene el motivo a nivel de campo.

429

Límite de tasa alcanzado. Espera y reintenta.

5xx

Transitorio. Reintenta con retroceso exponencial.

Paginación. Los endpoints de lista aceptan ?page=1&page_size=50 y devuelven { items: [...], total: N }.

Búsqueda. Donde se admite, ?search=… realiza una coincidencia sin distinción de mayúsculas.

IDs. Los recursos usan UUID. Trátalos como cadenas opacas.

Aislamiento de espacios. Tu clave está vinculada a una sola organización; la cabecera X-Organization-Id se ignora.

¿Listo para crear?

Emite una clave desde tu panel y empieza a enviar solicitudes en minutos.

Obtener una clave API
Prueba gratis