API DOCUMENTATION — VERSION 1.0

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-KeyYour secret API key
X-Agent-IDYour 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

FieldTypeRequiredDescription
phonestringRequiredPhone number with country code
namestringOptionalContact name for personalization
emailstringOptionalContact email address
metadataobjectOptionalCustom data for your agent

Response Examples

200Success
{
  "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": "conv_01k0gg6an6e6gape2e0hzap1zx",
  "agent_id": "agent_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
      }
    ]
  },
  "recording_url": "https://www.calldock.co/api/recordings/conv_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-EventEvent type (post_call)
X-Calldock-SignatureHMAC signature for verification

API Playground

Test the API Live

Try making a real API call right from your browser.

Authentication

Request Body

Response

Response will appear here...

Popular Integrations

Typeform logo

Typeform

Automatically call survey respondents

How it works:

When someone completes your Typeform, trigger an immediate follow-up call to qualify leads or gather feedback.

Example workflow:

Customer fills out "Request Demo" form → Calldock calls within 5 minutes → AI agent qualifies lead and books meeting

  • Real-time webhook triggers
  • Pass form answers to agent
  • Custom follow-up flows
Zapier logo

Zapier

Connect with 5,000+ apps instantly

How it works:

Create automated workflows that trigger calls based on events in your favorite tools.

Example workflow:

New Stripe payment → Wait 24 hours → Call customer for feedback → Log response in Slack

  • No-code workflow builder
  • Multi-step automations
  • Conditional call logic
HubSpot logo

HubSpot

Enhance your CRM with AI calling

How it works:

Automatically call leads based on CRM activities, lead scores, or deal stages.

Example workflow:

Lead score hits 80+ → Calldock calls hot lead → Updates deal stage based on call outcome

  • Lead score triggers
  • Deal stage automation
  • Contact property sync

Custom Integrations

Any platform that supports webhooks can integrate with Calldock

View integration examples →

Code Examples

curl -X POST https://api.calldock.co/v1/make-call \
  -H "X-API-Key: ck_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-Agent-ID: agent_XXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "metadata": {
      "source": "website",
      "campaign": "summer-promo"
    }
  }'

Error Handling

Status CodeDescriptionCommon Causes
200OKRequest successful-
400Bad RequestInvalid request formatMissing required fields, invalid phone format
401UnauthorizedInvalid authenticationMissing or invalid API key
429Too Many RequestsRate limit exceededToo many API calls in short period or rate limit hit
for a phone number/IP based on your agent settings
500Server ErrorInternal server errorTemporary server issues