CaveauCRM API & Integration Guide | Blue Note Logic Inc.

CRM Bot API Reference

The CRM Bot API exposes 13 actions for managing leads, calendar, tasks, notifications, and AI-powered insights. All requests are sent as POST with a JSON body containing the action name and parameters.

Base Configuration

Base URL: https://yourdomain.com/api/crm-bot/
Method: POST
Content-Type: application/json
Auth: Authorization: Bearer <token>
Body format: {"action": "leads.list", "params": {...}}

Lead Management

POST

Action: leads.list

List leads with optional status filter and date range. Returns normalized lead records.

status Filter by status (New, Assigned, In Process, etc.)
since_days Only leads from the last N days
limit Max results (1–50, default 20)

POST

Action: leads.get

Retrieve a single lead by its SuiteCRM UUID. Returns all lead fields including contact details and status history.

lead_id required — SuiteCRM lead UUID

POST

Action: leads.search

Search leads by name, email, or company. Searches across first_name, last_name, email, and account_name fields.

query required — Search term
limit Max results (1–30, default 10)

POST

Action: leads.create

Create a new lead in SuiteCRM. At minimum, a last_name (or first_name) is required.

first_name last_name email phone
company description lead_source status

POST

Action: leads.update

Update an existing lead. Pass any combination of fields to change.

lead_id required
Plus any: status first_name last_name email phone company description

Calendar

POST

Action: calendar.availability

Check available calendar slots in a date range. Returns open time slots and existing events.

date_from Start date, YYYY-MM-DD (default: today)
date_to End date (default: today + 5 days)
duration_minutes Slot length (default: 30)

POST

Action: calendar.book

Book a consultation on the CalDAV calendar. Creates a calendar event with attendee details.

datetime required — ISO format (e.g. 2026-03-30T10:00:00)
attendee_name required attendee_email required
topic Meeting subject (default: Consultation)
duration_minutes Duration (default: 30)

Tasks

POST

Action: tasks.list

List tasks from SuiteCRM with optional status filter.

status Filter (Not Started, In Progress, Completed, etc.)
limit Max results (1–50, default 20)

POST

Action: tasks.create

Create a new task in SuiteCRM. Status defaults to "Not Started".

name required — Task title
description priority (High/Medium/Low)
due_date YYYY-MM-DD format

Notifications & AI

POST

Action: notifications.pending

Get pending notifications: new leads today, overdue follow-ups (leads in "New" status > 48h), and today's calendar events.

No parameters required.

POST

Action: ai.summarize_lead

AI-powered lead summary using Claude. Analyzes lead data and provides actionable insights.

lead_id required

POST

Action: ai.draft_email

Generate an AI-drafted follow-up email for a lead. Optionally provide context for personalisation.

lead_id required
context Additional context (e.g. "follow up on demo request")

POST

Action: ai.qualify_lead

AI-powered lead qualification. Returns a score and recommendation based on lead data.

lead_id required

Example Requests

                                curl — List recent leads
                            

curl -X POST https://yourdomain.com/api/crm-bot/ \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "leads.list",
    "params": {
      "status": "New",
      "since_days": 7,
      "limit": 10
    }
  }'// Response
{
  "success": true,
  "data": [
    {
      "id": "abc-123-def-456",
      "first_name": "Ingrid",
      "last_name": "Nordberg",
      "email": "ingrid@example.com",
      "company": "Nordberg Consulting",
      "status": "New",
      "date_entered": "2026-03-28 10:30:00"
    }
  ]
}
                        

                                curl — Create a lead
                            

curl -X POST https://yourdomain.com/api/crm-bot/ \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "leads.create",
    "params": {
      "first_name": "Elena",
      "last_name": "Vasquez",
      "email": "elena@example.com",
      "company": "Iberian Analytics",
      "lead_source": "Web",
      "description": "Interested in CaveauCRM demo"
    }
  }'// Response
{
  "success": true,
  "data": {
    "id": "xyz-789-abc-012",
    "first_name": "Elena",
    "last_name": "Vasquez",
    "status": "New"
  }
}
                        

CaveauAI API Reference

The CaveauAI API provides health scoring and RAG knowledge base ingestion. These endpoints power the intelligence layer behind CaveauCRM.

Base Configuration

Base URL: https://yourdomain.com/api/caveau/
Auth: Authorization: Bearer <token>

GET

Endpoint: health-report.php

Compute and return health scores for all active clients. Each client receives a score from 0–100 mapped to green (80–100), amber (50–79), or red (0–49) risk levels.

No parameters required. Returns all active clients.

POST

Endpoint: ingest-ticket.php

Ingest a support ticket into the RAG knowledge base. The ticket content is chunked, embedded, and stored for AI-powered search and analysis.

ticket_id required — FOSSbilling ticket ID

                                curl — Health Report
                            

curl -X GET https://yourdomain.com/api/caveau/health-report.php \
  -H "Authorization: Bearer YOUR_API_TOKEN"// Response
{
  "status": "ok",
  "computed_at": "2026-03-28T07:00:00+01:00",
  "clients": [
    {
      "client_id": 1,
      "name": "Nordberg Consulting",
      "score": 95,
      "risk_level": "green",
      "deductions": [],
      "bonuses": ["Fast ticket resolution (+5)"]
    },
    {
      "client_id": 3,
      "name": "Rhein Tech GmbH",
      "score": 35,
      "risk_level": "red",
      "deductions": [
        "Open tickets: 3 (-30)",
        "Overdue invoices: 2 (-40)"
      ],
      "bonuses": ["Fast ticket resolution (+5)"]
    }
  ],
  "red_clients": 1,
  "total_clients": 5
}
                        

MCP Server Integration

CaveauCRM integrates with the Model Context Protocol (MCP), enabling AI assistants like Claude to manage your CRM through natural language. Ask questions, create leads, book meetings, and monitor client health — all conversationally.

What is MCP?

The Model Context Protocol (MCP) is an open standard by Anthropic that lets AI models interact with external tools and data sources. CaveauCRM exposes 14 MCP tools that map directly to the CRM Bot API and CaveauAI API endpoints.

Architecture

MCP Integration Flow

  Claude Code                    Claude Desktop
  │ (via SSH stdio)                │ (via SSE HTTP)
  │                                │
  └──────────┐          ┌──────────┘
            ▼          ▼
┌─────────────────────────────────────────┐
│        MCP Server (Python / FastMCP)      │
│                                         │
│  14 CRM Tools  +  9 Legal Knowledge Tools │
│                                         │
└───────────┬─────────────┬───────────────┘
            │             │
   HTTPS + Bearer   HTTPS + Bearer
            │             │
            ▼             ▼
┌──────────────┐  ┌──────────────────┐
│ CRM Bot API  │  │ CaveauAI API      │
│ 13 actions   │  │ Health + Ingest   │
└──────┬───────┘  └────────┬─────────┘
       │                      │
       ▼                      ▼
┌─────────────────────────────────────────┐
│  SuiteCRM  Baikal CalDAV  Claude AI    │
│  FOSSbilling  Qdrant  RAG Pipeline   │
└─────────────────────────────────────────┘

Available MCP Tools

MCP Tool	API Action	Description
`crm_list_leads`	leads.list	List CRM leads with optional filters
`crm_get_lead`	leads.get	Get a specific lead by ID
`crm_search_leads`	leads.search	Search leads by name, email, or company
`crm_create_lead`	leads.create	Create a new CRM lead
`crm_update_lead`	leads.update	Update an existing lead
`crm_check_availability`	calendar.availability	Check calendar availability
`crm_book_meeting`	calendar.book	Book a consultation meeting
`crm_list_tasks`	tasks.list	List CRM tasks
`crm_create_task`	tasks.create	Create a new task
`crm_get_notifications`	notifications.pending	Get pending notifications
`crm_summarize_lead`	ai.summarize_lead	AI-powered lead summary
`crm_draft_email`	ai.draft_email	AI-drafted follow-up email
`crm_qualify_lead`	ai.qualify_lead	AI lead qualification
`crm_health_report`	CaveauAI GET	Client health score report

Configuration

Add the MCP server to your Claude Code or Claude Desktop configuration:

                                .mcp.json — Claude Code
                            

{
  "mcpServers": {
    "caveaucrm": {
      "command": "ssh",
      "args": [
        "user@yourdomain.com",
        "/path/to/venv/bin/python /path/to/server.py --stdio"
      ]
    }
  }
}
                        

Natural Language Usage

Example Conversation

You: "Show me all new leads from this week"
Claude: calls crm_list_leads(status="New", since_days=7) → Returns a formatted list of recent leads

You: "Draft a follow-up email for the Nordberg lead"
Claude: calls crm_search_leads(query="Nordberg") then crm_draft_email(lead_id="...") → Returns a personalised email draft

You: "How are our clients doing?"
Claude: calls crm_health_report() → Returns a summary with green/amber/red scores

User Guide

Whether you're using the REST API directly, the MCP tools via Claude, or both — this guide covers the key workflows for getting the most out of CaveauCRM.

Getting Started

Step 1

Get Your API Token

Request a Bearer token from your administrator. This token authenticates all API and MCP requests.

Step 2

Configure MCP

Add the MCP server to your .mcp.json configuration to enable natural language CRM access from Claude.

Step 3

Make Your First Call

Try leads.list or notifications.pending to verify your setup. Or just ask Claude "show me today's notifications".

Managing Leads

Tip

Use leads.search to find leads by name, email, or company before performing updates. The search runs across all four fields simultaneously.

The lead management workflow follows a natural progression: list to see what's new, search to find specific contacts, create for new prospects, and update to change status or add notes. AI tools layer on top: summarize for quick context, qualify for scoring, and draft_email for personalised outreach.

Calendar Management

Business Hours

Calendar availability is computed against business hours: Monday – Friday, 09:00 – 17:00 CET. Slots outside these hours will not be returned by calendar.availability.

Always check availability first with calendar.availability, then book with calendar.book. The system creates a CalDAV event with the attendee's name, email, and meeting topic.

AI Features

Feature	Action	What It Does
Lead Summary	`ai.summarize_lead`	Generates a concise summary of the lead's profile, activity history, and recommended next steps.
Email Draft	`ai.draft_email`	Creates a personalised follow-up email based on lead data. Add context for more targeted messaging.
Lead Qualification	`ai.qualify_lead`	Scores the lead based on completeness, source quality, and engagement signals. Returns a recommendation.

Health Monitoring

Client health scores run on a weekly schedule and are available on-demand via the API. Scores start at 100 and are adjusted based on:

Deductions

Open tickets (each, cap -30) -10

Overdue invoices (each, cap -40) -20

Meeting gap (per day after 14d, cap -20) -1

Negative sentiment (3+ flagged) -15

No active order -10

Bonuses

Fast ticket resolution +5

Early invoice payment +5

Risk Level	Score Range	Action
Green	80 – 100	Healthy. No intervention needed.
Amber	50 – 79	At risk. Review recommended.
Red	0 – 49	Critical. Immediate attention required. Telegram alert sent.

Notifications

The notifications.pending action aggregates three notification types into a single response: new leads created today, overdue follow-ups (leads in "New" status for more than 48 hours), and today's calendar events. Use this as your daily morning check-in.

Authentication

All API endpoints require authentication via Bearer tokens. Inbound webhooks use HMAC-SHA256 signatures for verification.

Bearer Token Authentication

Every request to the CRM Bot API and CaveauAI API must include a Bearer token in the Authorization header:

                                HTTP Header
                            
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Tokens are validated server-side using timing-safe comparison to prevent timing attacks. Invalid or missing tokens return a 401 Unauthorized response.

Webhook Signature Verification

Inbound webhooks from CaveauCRM include an HMAC-SHA256 signature for payload verification. The signature is sent in the X-CaveauAI-Signature header:

                                PHP — Verify Webhook Signature
                            
// Received webhook$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_CAVEAUAI_SIGNATURE'] ?? '';

// Compute expected signature$expected = hash_hmac('sha256', $payload, $sharedSecret);

// Timing-safe comparisonif (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}
                        

Security Notes

HTTPS only — All API communication must use HTTPS. HTTP requests are rejected.
Timing-safe — Both Bearer token and HMAC signature verification use hash_equals() to prevent timing attacks.
Token rotation — Rotate API tokens periodically. Revoked tokens are rejected immediately.
Network isolation — Internal services (vector store, workflow engine, embeddings) are never exposed publicly. Only the API gateway handles external traffic.

API & Integration Guide

CRM Bot API Reference

Lead Management

Calendar

Tasks

Notifications & AI

Example Requests

CaveauAI API Reference

MCP Server Integration

Architecture

Available MCP Tools

Configuration

Natural Language Usage

User Guide

Getting Started

Managing Leads

Calendar Management

AI Features

Health Monitoring

Deductions

Bonuses

Notifications

Authentication

Bearer Token Authentication

Webhook Signature Verification

Ready to Integrate?