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
- Log into your Calldock dashboard
- Click on your profile dropdown in the top header
- Select "API Keys" from the dropdown menu
- Choose an agent and click "Generate" to create a new API key
- Copy the generated key immediately - it won't be shown again
Required Headers
X-API-Key
Your secret API keyX-Agent-ID
Your agent identifierKeep your API keys secure
Never expose API keys in client-side code or public repositories.
Make a Call
/v1/make-call
Create a new outbound call
Request Body
Field | Type | Required | Description |
---|---|---|---|
phone | string | Required | Phone number with country code |
name | string | Optional | Contact name for personalization |
email | string | Optional | Contact email address |
metadata | object | Optional | Custom data for your agent |
Response Examples
{ "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
- Log into your Calldock dashboard
- Click on your profile dropdown in the top header
- Select "API Keys" from the dropdown menu
- Find your agent and scroll to "Post-Call Webhook URL" section
- Enter your webhook endpoint URL (e.g., https://yourserver.com/webhook)
- Click "Save" to activate webhook notifications
- 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-Event
Event type (post_call)X-Calldock-Signature
HMAC signature for verificationAPI 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
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
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
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 Code | Description | Common Causes |
---|---|---|
200OK | Request successful | - |
400Bad Request | Invalid request format | Missing required fields, invalid phone format |
401Unauthorized | Invalid authentication | Missing or invalid API key |
429Too Many Requests | Rate limit exceeded | Too many API calls in short period or rate limit hit for a phone number/IP based on your agent settings |
500Server Error | Internal server error | Temporary server issues |