Developer API

Connect your agent anywhere with our simple API

Authentication

API Key Authentication

All API requests must include your API key and Agent ID in the request headers.

Getting Your API Key

1. Log into your Calldock dashboard
2. Click on your profile dropdown in the top header
3. Select "API Keys" from the dropdown menu
4. Choose an agent and click "Generate" to create a new API key
5. Copy the generated key immediately - it won't be shown again

Required Headers

X-API-Key Your secret API key
X-Agent-ID Your agent identifier

Keep your API keys secure

Never expose API keys in client-side code or public repositories.

Make a Call

POST /v1/make-call

Create a new outbound call

Request Body

Rate Limiting for API Calls

Pass optional fields to enable per-user rate limiting:

client_ip End-user's IP for IP-based limiting

client_fingerprint Unique user ID (requires Advanced Protection enabled)

• Phone number rate limiting works automatically when enabled

• Fingerprint limiting only works with Advanced Protection enabled

• Configure limits in Agent Settings Tab → Rate Limits

• API key limit (100 req/hr) always applies

Response Examples

200 Success

{
  "success": true,
  "data": {
    "callId": "call_abc123",
    "status": "initiated",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Post-Call Webhook

Webhook Configuration

Receive call data after each call completes

How to Add Webhook URL

1. Log into your Calldock dashboard
2. Click on your profile dropdown in the top header
3. Select "API Keys" from the dropdown menu
4. Find your agent and scroll to "Post-Call Webhook URL" section
5. Enter your webhook endpoint URL (e.g., https://yourserver.com/webhook)
6. Click "Save" to activate webhook notifications
7. Your endpoint will now receive POST requests after each call completes

Webhook Payload

{
  "webhook_version": "v1",
  "webhook_timestamp": "2024-01-15T10:35:00Z",
  "webhook_type": "post_call",
  "call_id": "cd_01k0gg6an6e6gape2e0hzap1zx",
  "agent_id": "cd_01jyxsjd3nfzrr76v4wv3zpfry",
  "phone_number": "+1234567890",
  "from_phone_number": "+13239776447",
  "status": "done",
  "intent": "account_setup",
  "intent_confidence": 0.9,
  "lead_data": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  },
  "duration_minutes": 2.35,
  "duration_seconds": 141,
  "start_time": "2024-01-15T10:30:00Z",
  "end_time": "2024-01-15T10:32:21Z",
  "call_successful": "success",
  "language": "en",
  "credits_deducted": 0.527,
  "metadata": {
    "summary": "John contacted support to inquire about...",
    "transcript": "Agent: Hey, is this John?\nUser: Yes...",
    "transcript_turns": [
      {
        "role": "agent",
        "message": "Hey, is this John?",
        "time_in_call_secs": 0
      },
      {
        "role": "user",
        "message": "Yes, this is John.",
        "time_in_call_secs": 2
      }
    ]
  },
  "data_collection": {
    "customer_name": "John Doe",
    "appointment_date": "2024-01-20",
    "preferred_time": "2:00 PM",
    "issue_type": "billing",
    "urgency_level": "high"
  },
  "recording_url": "https://www.calldock.co/api/recordings/cd_01k0gg6an6e6gape2e0hzap1zx"
}

Webhook Security

Signature Verification

All webhook requests include an HMAC signature header for security verification:

X-Calldock-Signature: 3a5b8c...

Finding your webhook secret: Go to API Keys → Select your agent → Copy the "Webhook Secret" displayed below your webhook URL.

Show verification examples

Node.js Example:

const crypto = require('crypto');

function verifyWebhook(payload, signature, webhookSecret) {
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(JSON.stringify(payload))
    .digest('hex');

return signature === expectedSignature;
}

// Usage in your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-calldock-signature'];
  const isValid = verifyWebhook(req.body, signature, 'your-webhook-secret');

if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

// Process webhook data
  res.status(200).send('OK');
});

Python Example:

import hmac
import hashlib
import json

def verify_webhook(payload, signature, webhook_secret):
    expected_signature = hmac.new(
        webhook_secret.encode('utf-8'),
        json.dumps(payload).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

return signature == expected_signature

# Usage in Flask
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Calldock-Signature')
    is_valid = verify_webhook(request.json, signature, 'your-webhook-secret')

if not is_valid:
        return 'Invalid signature', 401

# Process webhook data
    return 'OK', 200

Headers Included

X-Calldock-Event Event type (post_call)
X-Calldock-Signature HMAC signature for verification

API Playground

Test the API Live

Try making a real API call right from your browser.

Authentication

API Key *
Agent ID *

Request Body

Phone Number *
Name (Optional)
Email (Optional)
Client IP (Optional)
Client Fingerprint (Optional)
Metadata (Optional)

Add field

Send Test Request

Request Preview

Copy

curl -X POST https://api.calldock.co/v1/make-call \
  -H "X-API-Key: <your-api-key>" \
  -H "X-Agent-ID: <your-agent-id>" \
  -H "Content-Type: application/json" \
  -d '{
        "phone": "<your-phone-number>"
  }'

Response

Response will appear here...

Error Handling