# 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

| 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                        |
| `client_ip`        | string | Optional | End-user's IP for rate limiting (API calls only) |
| `client_fingerprint`| string | Optional | End-user's fingerprint for advanced rate limiting |

##### 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

```json
{
  "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

```json
{
  "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:

```javascript
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:

```python
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

```bash
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

| Status Code     | Description                    | Common Causes                                          |
|------------------|--------------------------------|-------------------------------------------------------|
| 200              | OK                             | -                                                     |
| 400              | Bad Request                    | Missing required fields, invalid phone format          |
| 401              | Unauthorized                   | Missing or invalid API key                             |
| 429              | Too Many Requests              | Too many API calls in short period or rate limit hit  |
| 500              | Server Error                   | Temporary server issues                                 |