BDM Documentation

Documentation API Documentation

BDM Plain CRM API

Complete REST API reference for integrating with BDM Plain CRM, including authentication, endpoints, and examples.

Quick Reference

Base URL: https://your-domain.com/api/crm
Authentication: Bearer Token
Rate Limit: 1000 requests/hour
Content-Type: application/json

Table of Contents

Authentication Overview Endpoints Contacts API Deals API Tasks API Activities API Integrations Webhooks Error Handling Rate Limiting

Authentication

API Key Authentication

BDM Plain CRM uses Bearer token authentication. Include your API key in the Authorization header of every request.

Authorization: Bearer bdm_crm_your_api_key_here

Security Note: Never expose your API keys in client-side code or public repositories. Store them securely as environment variables.

Getting API Keys

  1. Log into your BDM Plain CRM account
  2. Navigate to Settings → API Keys
  3. Click "Create New API Key"
  4. Configure permissions and domain restrictions
  5. Copy the generated key (shown only once)

Overview Endpoints

Get CRM Overview

GET
/api/crm/overview

Get CRM statistics overview for dashboard widgets

Response Example:

{
  "success": true,
  "data": {
    "contacts": {
      "total": 150,
      "active": 120,
      "prospects": 25,
      "customers": 95
    },
    "deals": {
      "total": 45,
      "open": 32,
      "value": 125000
    },
    "tasks": {
      "total": 28,
      "overdue": 5,
      "today": 8
    }
  }
}

Contacts API

List Contacts

GET
/api/crm/contacts

Get paginated list of contacts with filtering

Parameters:

  • type - lead, prospect, customer
  • status - active, inactive
  • search - Search term
  • per_page - Items per page (max 100)

Create Contact

POST
/api/crm/contacts

Create new contact

Request Body:

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "job_title": "CEO",
  "company_id": 1,
  "status": "prospect",
  "source": "website",
  "priority": "high"
}

Deals API

List Deals

GET
/api/crm/deals

Get paginated list of deals with filtering

Parameters:

  • status - open, closed, won, lost
  • contact_id - Filter by contact
  • min_value - Minimum deal value
  • max_value - Maximum deal value

Update Deal Status

PUT
/api/crm/deals/{id}/status

Update deal status (commonly used for pipeline automation)

Tasks API

List Tasks

GET
/api/crm/tasks

Get paginated list of tasks with filtering

Parameters:

  • status - pending, in_progress, completed, cancelled
  • priority - low, medium, high
  • contact_id - Filter by associated contact
  • overdue - true/false

Activities API

Log Activity

POST
/api/crm/activities

Log new activity (used by other apps to track interactions)

Request Body:

{
  "contact_id": 1,
  "type": "email_sent",
  "title": "Follow-up Email Sent",
  "description": "Sent pricing information",
  "source_app": "external-app",
  "metadata": {
    "email_subject": "Pricing Information",
    "campaign_id": "camp_123"
  }
}

BDM Integration Endpoints

BDM Ecosystem Integration: These endpoints are specifically designed for seamless integration with other BDM applications.

BDM Mailer Integration

/api/crm/integrations/mailer/contacts GET

Get contacts formatted for email campaigns

/api/crm/integrations/mailer/email-sent POST

Webhook to log email activity from BDM Mailer

BDM Accounting

  • GET /integrations/accounting/customers
  • POST /integrations/accounting/invoice-sent

BDM Time Log

  • GET /integrations/timelog/clients
  • POST /integrations/timelog/time-logged

Webhooks

General Webhook

POST
/api/crm/webhook

General webhook endpoint for external integrations

Use Cases:

  • • Log activities from external applications
  • • Sync contact status changes from third-party tools
  • • Track interaction events from website forms
  • • Update deal stages from external sales tools

Error Handling

HTTP Status Codes

Status Description
200 Success
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
429 Rate Limit Exceeded

Error Response Format

{
  "success": false,
  "message": "Error description",
  "errors": {
    "field_name": ["Validation error message"]
  }
}

Rate Limiting

Default Rate Limit: API keys are limited to 1000 requests per hour by default. You can configure custom limits when creating API keys.

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1640995200

Best Practices

  • • Monitor rate limit headers
  • • Implement exponential backoff
  • • Cache responses when possible
  • • Use batch operations where available

Integration Examples

PHP Example

<?php
// Create a new contact via API
$apiKey = 'bdm_crm_your_api_key_here';
$baseUrl = 'https://yourdomain.com/api/crm';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/contacts');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'first_name' => 'John',
    'last_name' => 'Doe',
    'email' => 'john@example.com',
    'status' => 'prospect'
]));

$response = curl_exec($ch);

if ($response !== false) {
    $data = json_decode($response, true);
    
    if ($data && isset($data['success']) && $data['success']) {
        echo "Contact created successfully!";
    } else {
        echo "Error: " . ($data['message'] ?? 'Unknown error');
    }
} else {
    echo "cURL Error: " . curl_error($ch);
}

curl_close($ch);
?>

JavaScript Example

// Fetch CRM overview data
async function getCrmOverview() {
    const apiKey = 'bdm_crm_your_api_key_here';
    const baseUrl = 'https://yourdomain.com/api/crm';
    
    try {
        const response = await fetch(`${baseUrl}/overview`, {
            headers: {
                'Authorization': `Bearer ${apiKey}`,
                'Content-Type': 'application/json'
            }
        });
        
        const data = await response.json();
        
        if (data.success) {
            console.log('Total contacts:', data.data.contacts.total);
            console.log('Open deals:', data.data.deals.open);
        }
    } catch (error) {
        console.error('Error:', error);
    }
}

getCrmOverview();

BDM Plain CRM API Documentation v1.0