REST API Documentation

Programmatic access to every call, transcript, recording, and analytic for your AI receptionist. Available on the Enterprise plan ($1,997/mo). All responses are JSON. Base URL:

https://humanaddai.com/api/v1

Authentication

Authenticate every request with your API key in the Authorization header. Get your key from the Dashboard → Integrations tab → Custom API card. You can rotate it at any time; the old key dies instantly.

curl https://humanaddai.com/api/v1/calls \
  -H "Authorization: Bearer hak_your_api_key_here"

Never commit your key to version control. If it's ever exposed, rotate immediately from the dashboard.

Errors

All errors return a JSON body with an error code and a human message.

{ "ok": false, "error": "invalid_api_key", "message": "API key not recognized." }

Rate limits

60 requests per minute per API key. Exceeding returns 429 Too Many Requests.

GET /api/v1/calls

Returns your most recent calls. Paginated via after timestamp.

Query params

• limit — integer, 1–200, default 50
• after — unix ms timestamp; only returns calls that started after this

Example

curl "https://humanaddai.com/api/v1/calls?limit=10" \
  -H "Authorization: Bearer hak_..."

{
  "ok": true,
  "count": 10,
  "calls": [
    {
      "call_id": "call_abc123",
      "direction": "inbound",
      "from_number": "+15551234567",
      "to_number":   "+15559876543",
      "started_at":  "2025-01-15T18:22:04.000Z",
      "duration_seconds": 82,
      "status": "ended",
      "sentiment": "positive",
      "summary": "Caller booked an HVAC maintenance appointment for Thursday.",
      "tags": ["booking"],
      "booked": true
    }
  ]
}

GET /api/v1/calls/:id

Full call details including transcript and a proxied recording URL.

curl https://humanaddai.com/api/v1/calls/call_abc123 \
  -H "Authorization: Bearer hak_..."

{
  "ok": true,
  "call": {
    "call_id": "call_abc123",
    "direction": "inbound",
    "from_number": "+15551234567",
    "to_number":   "+15559876543",
    "started_at":  "2025-01-15T18:22:04.000Z",
    "ended_at":    "2025-01-15T18:23:26.000Z",
    "duration_seconds": 82,
    "status": "ended",
    "disconnection_reason": "user_hangup",
    "sentiment": "positive",
    "summary": "...",
    "transcript": "AI: Hello...",
    "transcript_object": [...],
    "recording_url": "/api/v1/calls/call_abc123/recording"
  }
}

GET /api/v1/calls/:id/recording

Streams the call audio as audio/wav. Proxied so you never see the upstream URL.

GET /api/v1/stats

Aggregate metrics for a rolling period.

Query params

• days — integer, default 30

{
  "ok": true,
  "period_days": 30,
  "stats": {
    "totalCalls": 426,
    "avgDuration": "1:22",
    "answered": 402,
    "missed": 24,
    "inbound": 410,
    "outbound": 16,
    "sentimentDistribution": { "positive": 380, "neutral": 32, "negative": 14 },
    "busiestDay": "Tuesday",
    "peakHours": "9am - 12pm",
    "topQuestions": [...]
  }
}

POST /api/v1/kb

Update your AI's knowledge base programmatically. Changes are queued for review and pushed within minutes.

curl https://humanaddai.com/api/v1/kb \
  -H "Authorization: Bearer hak_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "Our new hours are 8am-7pm M-F.", "replace": false}'

{ "ok": true, "queued": true }

Set replace: true to wipe the existing KB before adding. Use with caution.

Receiving webhooks (outbound)

Configure a webhook URL in Dashboard → Integrations and we'll POST every call_ended event to your endpoint. See the dashboard for payload shape, or receive this JSON:

{
  "event": "call_ended",
  "call_id": "...",
  "direction": "inbound",
  "from_number": "+15551234567",
  "to_number": "+15559876543",
  "started_at": "2025-01-01T00:00:00Z",
  "duration_seconds": 82,
  "sentiment": "positive",
  "summary": "...",
  "transcript": "...",
  "recording_url": "..."
}

If you set a secret in the dashboard, it's sent as X-Webhook-Secret — verify it before processing.