REST API Documentation
Use our REST API to send form responses directly to CallMeBack from your backend. This gives you full control over data validation, processing, and integration with your existing systems.
API Overview
Secure
HTTPS-only with API key authentication
Fast
Real-time processing with sub-second response times
Simple
RESTful design with JSON request/response
Authentication
All API requests require authentication using your API key. Include it in the Authorization header.
Authorization Header:
Authorization: Bearer YOUR_API_KEY
Where to find your API key:
- 1. Log into your CallMeBack dashboard
- 2. Go to "Settings" → "API"
- 3. Generate a new API key
- 4. Copy and store it securely
Base URL
Production:
https://yourdomain.com/api/v1
Sandbox (for testing):
https://sandbox.yourdomain.com/api/v1
Submit Form Response
Endpoint:
POST /form_responses
Request Headers:
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
Request Body:
{
"form_response": {
"domain_id": "your-domain-id",
"form_data": {
"name": "John Doe",
"email": "john@example.com",
"phone": "+1234567890",
"message": "I'm interested in your services"
},
"form_type": "contact",
"source_url": "https://yourwebsite.com/contact",
"user_agent": "Mozilla/5.0...",
"ip_address": "192.168.1.1"
}
}
Response (Success - 201):
{
"id": "form_response_123",
"status": "created",
"lead_id": "lead_456",
"callback_scheduled": false,
"created_at": "2024-01-15T10:30:00Z"
}
Code Examples
JavaScript (Node.js)
const axios = require('axios');
const submitFormResponse = async (formData) => {
try {
const response = await axios.post('https://yourdomain.com/api/v1/form_responses', {
form_response: {
domain_id: 'your-domain-id',
form_data: formData,
form_type: 'contact',
source_url: 'https://yourwebsite.com/contact',
user_agent: navigator.userAgent,
ip_address: '192.168.1.1'
}
}, {
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
}
});
console.log('Form submitted successfully:', response.data);
return response.data;
} catch (error) {
console.error('Error submitting form:', error.response?.data || error.message);
throw error;
}
};
// Usage
submitFormResponse({
name: 'John Doe',
email: 'john@example.com',
phone: '+1234567890',
message: 'I\'m interested in your services'
});
PHP
<?php
function submitFormResponse($formData) {
$apiKey = 'YOUR_API_KEY';
$domainId = 'your-domain-id';
$data = [
'form_response' => [
'domain_id' => $domainId,
'form_data' => $formData,
'form_type' => 'contact',
'source_url' => 'https://yourwebsite.com/contact',
'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
'ip_address' => $_SERVER['REMOTE_ADDR'] ?? ''
]
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://yourdomain.com/api/v1/form_responses');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $apiKey
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 201) {
$result = json_decode($response, true);
return $result;
} else {
throw new Exception('API request failed: ' . $response);
}
}
// Usage
try {
$result = submitFormResponse([
'name' => 'John Doe',
'email' => 'john@example.com',
'phone' => '+1234567890',
'message' => 'I\'m interested in your services'
]);
echo "Form submitted successfully!";
} catch (Exception $e) {
echo "Error: " . $e->getMessage();
}
?>
Python
import requests
import json
def submit_form_response(form_data):
api_key = 'YOUR_API_KEY'
domain_id = 'your-domain-id'
url = 'https://yourdomain.com/api/v1/form_responses'
headers = {
'Content-Type': 'application/json',
'Authorization': f'Bearer {api_key}'
}
data = {
'form_response': {
'domain_id': domain_id,
'form_data': form_data,
'form_type': 'contact',
'source_url': 'https://yourwebsite.com/contact',
'user_agent': 'Mozilla/5.0...',
'ip_address': '192.168.1.1'
}
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
result = response.json()
print('Form submitted successfully:', result)
return result
except requests.exceptions.RequestException as e:
print('Error submitting form:', e)
raise
# Usage
form_data = {
'name': 'John Doe',
'email': 'john@example.com',
'phone': '+1234567890',
'message': 'I\'m interested in your services'
}
submit_form_response(form_data)
Error Handling
Common Error Responses:
401 Unauthorized
{
"error": "Invalid API key"
}
422 Unprocessable Entity
{
"error": "Validation failed",
"details": {
"form_data.email": ["is invalid"],
"form_data.phone": ["is required"]
}
}
429 Too Many Requests
{
"error": "Rate limit exceeded",
"retry_after": 60
}
Rate Limits
To ensure fair usage, API requests are rate limited based on your plan.
Free Plan
100 requests/hour
Pro Plan
1,000 requests/hour
Enterprise
10,000 requests/hour
Rate Limit Headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642243200
Webhooks
Receive real-time notifications when callbacks are scheduled, completed, or when leads are updated.
Webhook Events:
- •
form_response.created
- New form submission - •
callback.scheduled
- Callback scheduled - •
callback.completed
- Callback completed - •
lead.updated
- Lead information updated
Webhook Payload Example:
{
"event": "form_response.created",
"data": {
"id": "form_response_123",
"lead_id": "lead_456",
"form_data": {
"name": "John Doe",
"email": "john@example.com"
},
"created_at": "2024-01-15T10:30:00Z"
}
}
Next Steps
Test Your Integration
- • Use the sandbox environment for testing
- • Verify all required fields are sent
- • Test error handling scenarios
- • Monitor response times
Production Deployment
- • Switch to production API endpoint
- • Implement proper error handling
- • Set up webhook endpoints
- • Monitor API usage and limits