API

Build with the Perbene API

REST API for managing contacts, service requests, technicians, scheduling, calls, messages, leads, and your knowledge base, from external agents, integrations, or your own automations.

01 / Authentication

Get started in 3 steps

Get an API key
  1. 01

    Issue an API key

    Go to Profile settings → API Keys and click Generate key. Copy it once. It’s shown only at creation.

  2. 02

    Set the env var

    export PERBENE_API_KEY=pbn_live_…

  3. 03

    Call the API

    Send X-API-Key on every request to https://api.perbene.ai. Your key is bound to your organization.

02 / First request

curl

List the contacts in your tenant.

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

Python

A drop-in client using 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

The most useful endpoints for agents and integrations. For full request/response schemas see the live OpenAPI spec.

Contacts

  • GET/api/contactsList with search, pagination
  • GET/api/contacts/searchLightweight search
  • POST/api/contactsCreate a contact
  • PUT/api/contacts/{id}Update

Leads

  • GET/api/leadsList qualified leads
  • POST/api/leadsCreate a lead
  • PUT/api/leads/{id}Update

Service requests

  • GET/api/service-requestsList jobs / work orders
  • POST/api/service-requestsCreate one
  • PUT/api/service-requests/{id}Update status, notes
  • POST/api/service-requests/{id}/quoteAttach a quote
  • POST/api/service-requests/{id}/emergencyEscalate to urgent
  • GET/api/quotes/pendingPending-quote list
  • GET/api/emergencies/activeActive urgent SRs

Service listings & providers

  • GET/api/service-listingsCatalog of services offered
  • POST/api/service-listingsAdd a listing
  • GET/api/service-providersExternal providers
  • POST/api/service-providersAdd a provider

Technicians & dispatch

  • GET/api/techniciansList technicians
  • POST/api/techniciansAdd a technician
  • GET/api/technicians/on-call/currentWho is on call now
  • GET/api/technicians/on-call/scheduleOn-call rotation
  • POST/api/technicians/dispatchDispatch a tech to a job
  • GET/api/technicians/dispatch/activeActive dispatches
  • PUT/api/technicians/dispatch/{id}Update status / ETA

Scheduling (appointments)

  • GET/api/scheduling/typesList appointment types
  • POST/api/scheduling/check-availabilityFind open slots
  • POST/api/scheduling/bookBook a slot for a contact
  • POST/api/scheduling/manageReschedule or cancel
  • GET/api/scheduling/appointmentsList bookings

Outbound campaigns

  • POST/api/campaigns/quick-callOne-off call to a phone number
  • POST/api/campaigns/entity-callOne-off call to a known contact / lead
  • POST/api/campaignsCreate a multi-contact campaign
  • POST/api/campaigns/{id}/contacts/uploadCSV upload
  • POST/api/campaigns/{id}/startLaunch / resume
  • POST/api/campaigns/{id}/pausePause
  • GET/api/campaigns/{id}/contactsPer-contact status & dispositions

Calls, messages, conversations

  • GET/api/callsList call records
  • GET/api/calls/{id}Detail with transcript
  • GET/api/calls/{id}/recordingRecording URL
  • GET/api/messagesSMS messages
  • GET/api/conversationsMulti-channel threads
  • POST/api/conversations/{id}/messagesAppend a message

Knowledge base & RAG

  • GET/api/knowledge-base/sourcesList sources
  • POST/api/knowledge-base/sourcesAdd a source (URL or text)
  • POST/api/knowledge-base/sources/uploadUpload a file
  • POST/api/knowledge-base/searchRAG search the agent uses

Urgent alerts, dispositions, DNC

  • GET/api/urgent-alertsList urgent alerts
  • POST/api/urgent-alertsCreate one
  • GET/api/dispositionsCall-outcome categories
  • GET/api/dncDo Not Call list
  • GET/api/dnc/check/{phone}Check a phone
  • POST/api/dnc/bulkBulk upload

Stats & activity

  • GET/api/statistics/dashboardTop-line counters
  • GET/api/statistics/metrics/time-seriesMetrics over time
  • GET/api/statistics/service-requests/by-statusStatus histogram
  • GET/api/activitiesRecent agent activity

04 / Resilience

Errors & patterns

401

Missing, revoked, or expired key. Re-issue from the dashboard.

403

Endpoint requires a higher role. You should not see this with a normal API key.

404

Resource doesn't exist or belongs to another tenant.

422

Validation failed. Body has the field-level reason.

429

Rate-limited. Back off and retry.

5xx

Transient. Retry with exponential backoff.

Pagination. List endpoints accept ?page=1&page_size=50 and return { items: [...], total: N }.

Search. Where supported, ?search=… does a case-insensitive match.

IDs. Resources use UUIDs. Treat them as opaque strings.

Tenant isolation. Your key is bound to one organization; the X-Organization-Id header is ignored.

Ready to build?

Issue a key from your dashboard and start sending requests in minutes.

Get an API key
Start free trial