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. 1. Log into your CallMeBack dashboard
  2. 2. Go to "Settings" → "API"
  3. 3. Generate a new API key
  4. 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

Need Help?

Our support team is here to help you with your integration.

Contact Support
Cookie Policy %>