Dialbotix
API reference

REST API reference

A small, consistent JSON API. All requests are HTTPS, all errors are RFC 7807-style problem responses.

Bearer JWT

Sign in once via /api/auth/login, then attach the token to every request.

Per-tenant scope

Tokens are scoped to the user's workspace. No cross-tenant access.

Realtime via Socket.IO

Subscribe to new_lead / lead_updated for live UIs.

Quickstart

Authenticate, then create a lead — the AI voice agent dials it within seconds.

curl
# 1. Authenticate
curl -X POST https://api.dialbotix.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"…"}'
 
# → { "token": "eyJ…", "user": { ... } }
 
# 2. Create a lead — the AI will dial within seconds
curl -X POST https://api.dialbotix.com/api/leads \
  -H "Authorization: Bearer eyJ…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah Mitchell",
    "phone": "+15550123456",
    "email": "sarah@example.com",
    "campaign_id": 12
  }'
 
# → { "id": 8421, "message": "Lead created", "queued": true }

Endpoints

Grouped by resource. All paths are relative to https://api.dialbotix.com.

Auth
POST
/api/auth/login

Exchange email + password for a JWT.

GET
/api/auth/me

Return the current authenticated user.

Leads
GET
/api/leads

List leads scoped to the calling user.

POST
/api/leads

Create a lead and queue an AI call.

POST
/api/manual-leads/create

Create a manual-source lead through the manual-leads module.

Campaigns
GET
/api/campaigns

List user-scoped campaigns with stats.

POST
/api/campaigns

Create a campaign (script, retries, timezone, booking link).

PATCH
/api/campaigns/:id

Update a campaign — partial fields supported.

Analytics
GET
/api/analytics/overview

Totals + per-campaign breakdown.

GET
/api/analytics/timeseries

Last 12 months of leads / calls / bookings.

Billing
GET
/api/billing/subscription

Current plan, status, period end.

POST
/api/billing/checkout

Returns Paddle overlay parameters for the frontend.

POST
/api/billing/cancel

Cancel the current subscription at the end of the billing period.

Webhooks

Inbound webhook URLs Dialbotix exposes. Each one verifies its signature and is idempotent on the provider's event id.

IN
/api/webhook/lead/:campaignId

Public lead intake from forms / ad platforms / CRMs.

IN
/api/webhook/vapi

Vapi end-of-call event with transcript + recording.

IN
/api/webhooks/hubspot

HubSpot CRM events. Signed with HMAC-SHA256.

IN
/api/billing/webhook

Paddle subscription + transaction lifecycle events. Signed with HMAC-SHA256.

Error format

All errors return JSON with a message field plus the appropriate HTTP status.

401
Missing or invalid token

Re-authenticate via /api/auth/login.

403
Not authorized

Token is valid but you can't access this resource.

404
Not found

Resource not found or not yours — we don't leak existence.

429
Rate limited

Back off per the Retry-After header.