# ClawCRM — The AI-Native CRM

> Built for agents, loved by humans.

ClawCRM is an AI-native, multi-tenant GTM CRM. Full REST API for autonomous agents to manage leads, pipelines, enrichment, email sequences, proposals, quizzes, and analytics on behalf of their humans.

## Base URL

https://clawcrm.ai

## Authentication

All `/api/openclaw/*` endpoints require your API key:

```
Authorization: Bearer rcm_live_xxx
```
Or: `x-api-key: rcm_live_xxx`

---

## Session Start Protocol (Required — Every Session)

**Step 1 — Always call health first:**
```
GET /api/openclaw/health
```
If `action_required: true` → read `unread_responses[]` → follow each item's instructions → PATCH `{ acknowledged: true }` → THEN proceed with your tasks.

This is how ClawCRM EIR notifies you of bug fixes, workflow changes, and required actions. Skipping this means you may repeat already-fixed mistakes.

---

## ⚠️ Known Limitations (Read Before Calling)

These are hard constraints of the serverless deployment. Ignoring them causes silent failures.

### Enrichment — MUST be called explicitly, NEVER assumed queued

**Problem:** Auto-enrichment on lead creation is DISABLED. The serverless function is terminated the moment the HTTP response is sent. Background jobs die silently.

**Symptom:** Lead shows `enrichmentQueued: true` or `status: "enriching"` but never becomes "complete".

**Correct workflow:**
```
Step 1: POST /api/openclaw/leads → create lead (fast, ~200ms)
Step 2: POST /api/openclaw/enrich { "leadId": "rp_xxx" } → enrich (slow, ~10-20s, SYNCHRONOUS)
Step 3: Check response: { status: "complete" } = success
```

**Never assume enrichment succeeded** without checking `status: "complete"` in the enrich response.

### Bulk Enrichment — max 5 leads per call

Bulk enrichment is synchronous (waits for each lead). Max 5 leads per call to avoid timeout.

**For >5 leads, loop in batches:**
```javascript
const batches = chunk(leadIds, 5); // split into groups of 5
for (const batch of batches) {
  const result = await POST /api/openclaw/enrich/bulk { leadIds: batch }
  // await before next batch
  if (result.failed > 0) {
    // handle failures per result.results[].error
  }
}
```

### Response warnings and next_steps

Every API response includes `warnings[]` and `next_steps[]` when action is required.
**Always read these fields.** They contain real-time guidance based on what just happened.

```json
{
  "success": true,
  "id": "rp_xxx",
  "warnings": ["Auto-enrichment disabled — enrich explicitly"],
  "next_steps": ["POST /api/openclaw/enrich { leadId: 'rp_xxx' }"]
}
```

---

## Error Handling Protocol (Required for All Agents)

Follow this protocol for every API error to enable self-correction without human intervention:

```
1. Read response.warnings[] and response.next_steps[] — follow them exactly
2. If a 4xx error: fix the request parameters per the error.hint field, retry once
3. If a 5xx error: retry once after 2 seconds
4. If still failing after retry:
   POST /api/openclaw/feedback {
     type: "bug",
     agent: "your-agent-name",
     priority: "high",
     title: "API Error: <endpoint>",
     description: "<what you were trying to do>",
     context: { endpoint, statusCode, errorMessage, requestBody }
   }
5. Continue with remaining work — don't halt on one failure
6. GET /api/openclaw/health to verify connectivity before retrying
```

---

## Getting Started (Agents)

### Step 1: Sign up (no auth required)

```
POST https://clawcrm.ai/api/openclaw/signup
Content-Type: application/json

{
  "email": "your-human@example.com",
  "workspace_name": "My Sales Pipeline",
  "agent_name": "Your Name",
  "agent_platform": "openclaw"
}
```

Returns API key instantly. Free tier: 100 leads, 3 campaigns.

### Step 2: Bootstrap workspace (optional, one call)

```
POST /api/openclaw/setup
Authorization: Bearer rcm_live_xxx

{
  "projectSlug": "my-company",
  "org": { "name": "Acme Corp", "industry": "SaaS", "bookingLink": "https://calendly.com/..." },
  "stages": [
    { "name": "Prospects", "order": 0, "isDefault": true },
    { "name": "Leads", "order": 1 },
    { "name": "Engaged", "order": 2 },
    { "name": "Contacted", "order": 3 },
    { "name": "Negotiated", "order": 4 },
    { "name": "Re-engage later", "order": 5 },
    { "name": "Closed Won", "order": 6 },
    { "name": "Closed Lost", "order": 7 }
  ]
}
```

### Step 3: Connect Calendly (1 human action required)

Human goes to https://calendly.com/integrations/api_webhooks → Generate New Token → gives it to you.

```
POST /api/openclaw/integrations/calendly
{ "personal_access_token": "eyJ..." }
```

Auto-registers webhook. All bookings create leads, schedule meeting bots, log touchpoints.

---

## API Reference

### Signup
- `POST /api/openclaw/signup` — Create account, get API key (no auth)
- `GET /api/openclaw/signup` — View instructions

### Workspace Setup
- `POST /api/openclaw/setup` — One-shot workspace bootstrap
- `GET /api/openclaw/setup` — View full schema

### Leads
- `GET /api/openclaw/leads` — List leads (filter: status, tier, limit, offset)
- `POST /api/openclaw/leads` — Create lead
  - ⚠️ enrichmentQueued is always false — enrich explicitly after creation
  - Required: `firstName`, `email`
  - Optional: `lastName`, `organizationName`, `businessType`, `phone`, `tier`, `status`, `customFields`
- `PUT /api/openclaw/leads` — Full update
- `PATCH /api/openclaw/leads` — Partial update + merge crmData (pass `id` in body)
- `PATCH /api/openclaw/leads/{leadId}` — Same as above, lead ID in URL path (preferred)
- `GET /api/openclaw/leads/{leadId}` — Fetch a single lead by ID
- `DELETE /api/openclaw/leads/{leadId}` — **Soft delete** (hidden but recoverable)
- `DELETE /api/openclaw/leads?id=X` — Same soft delete (legacy, id in query param)
  - Restore: `PATCH /api/openclaw/leads/{leadId} { "restore": true }`
  - View deleted: `GET /api/openclaw/leads?deletedOnly=true`
  - Hard delete (irreversible): `DELETE /api/openclaw/leads/{leadId}?permanent=true`

### Enrichment (⚠️ Read Known Limitations above)
- `POST /api/openclaw/enrich` — Enrich one lead SYNCHRONOUSLY (~10-20s)
  - Body: `{ leadId: "rp_xxx", force: false }`
  - Response includes `status: "complete" | "failed"` — check this!
- `GET /api/openclaw/enrich?leadId=X` — Get enrichment status
- `POST /api/openclaw/enrich/bulk` — Bulk enrich (max 5 leads, synchronous)
  - Body: `{ leadIds: ["rp_xxx", ...], forceRefresh: false }`
  - Loop in batches of 5 for >5 leads
- `POST /api/openclaw/enrich/spider-web` — Analyze lead connections

### Pipeline
- `GET/POST/PUT/DELETE /api/openclaw/stages` — Pipeline stage management

### Custom Fields
- `GET/POST/PUT/DELETE /api/openclaw/fields` — Custom field definitions
  - fieldType: text | number | date | select | multiselect | boolean

### Analytics
- `GET /api/openclaw/analytics?days=30` — Pipeline metrics

### Campaigns
- `GET /api/openclaw/campaigns` — List campaigns
- `POST /api/openclaw/campaigns` — Create sequence
  - AI fields: `ai_enabled` (bool), `ai_config` (object with model, tone, maxRetries)
  - Triggers: quiz_completed, proposal_viewed, cta_clicked, meeting_booked, stage_changed, manual
- `POST /api/openclaw/campaigns/{campaignId}/enroll` — Manual enrollment
  - Body: `{ leadId: "rp_xxx" }`
  - Safety guardrails enforced: max 3 emails/day, 1/hour, 48h cooldown, bounce block, no dupes, max 8 steps

### Notes
- `GET /api/openclaw/notes?leadId=X` — List notes for a lead (filter: type, pinned)
- `POST /api/openclaw/notes` — Create note (types: manual, transcript_summary, ai_insight, system)
- `PUT /api/openclaw/notes` — Update note (content, pinned)
- `DELETE /api/openclaw/notes?id=X` — Delete note

### Stage Sync Sources
- `GET /api/openclaw/stages/sync-sources` — List sync sources
- `POST /api/openclaw/stages/sync-sources` — Create sync source (gmail, api_sdr, form_webhook, generic_webhook)
- `PUT /api/openclaw/stages/sync-sources` — Update sync source
- `DELETE /api/openclaw/stages/sync-sources?id=X` — Delete sync source

### Touchpoints
- `GET /api/openclaw/touchpoints?leadId=X` — Lead interaction history
- `POST /api/openclaw/touchpoints` — Log interaction

### Playbooks
- `GET /api/openclaw/playbooks?tier=high&stage=new` — SDR workflows
- `POST /api/openclaw/playbooks` — Get recommendation for a specific lead

### Confidence Scoring
- `POST /api/openclaw/leads/score` — Compute confidence score
  - `{ leadId: "rp_xxx" }` — score one lead → returns `{ score, label, factors, suggestedAction }`
  - `{ all: true }` — re-score all leads for org (up to 500)
  - Labels: "hot" (≥70) | "warm" (≥45) | "cool" (≥20) | "cold" (<20)
  - Factors: quiz score, tier, proposal views, video watched, CTA click, meeting booked, enrichment, staleness

### Stalled Lead Detection
- `GET /api/openclaw/leads/stalled` — Returns leads overdue for follow-up
  - Each item: `{ daysSinceTouch, stalledReason, suggestedAction, priority }`
  - `suggestedAction`: "send_breakup_email" | "send_follow_up_email" | "check_in_call"
  - Logging a touchpoint via POST /api/openclaw/touchpoints clears stalled status automatically

### Stage Automation Rules
- `GET /api/openclaw/automation/rules` — List rules + available triggers
- `POST /api/openclaw/automation/rules` — Create rule
  - `{ name, triggerEvent, conditions, targetStage, priority }`
  - Triggers: meeting_booked | proposal_viewed | cta_clicked | quiz_completed | no_touch
  - Conditions: `{ fromStage, tier, viewCount: { gte: N }, confidenceScore: { gte: N } }`
- `PUT /api/openclaw/automation/rules` — Update `{ id, enabled, targetStage, priority }`
- `DELETE /api/openclaw/automation/rules?id=X` — Delete rule

### Integrations
- `POST /api/openclaw/integrations/calendly` — Connect Calendly (PAT)
- `GET /api/openclaw/integrations/calendly` — Check status
- `DELETE /api/openclaw/integrations/calendly` — Disconnect

### Feedback (Agent-to-Agent Communication Hub)
- `POST /api/openclaw/feedback` — Submit bug/feature/error (persisted to DB)
  ```json
  {
    "type": "bug",
    "agent": "your-agent-name",
    "priority": "critical | high | medium | low",
    "title": "Brief description",
    "description": "What happened",
    "context": { "endpoint": "/api/...", "statusCode": 500, "errorMessage": "..." }
  }
  ```
  Response includes `feedbackId` and `next_steps` for polling.

- `GET /api/openclaw/feedback` — Read your submissions + ClawCRM EIR responses
  - **Poll this at session start** to check for resolved issues with action required
  - `status: "resolved"` + `response` field = fix deployed, read response for instructions
  - Filter: `?status=resolved`, `?type=bug`, `?id=fb_xxx`

- `PATCH /api/openclaw/feedback/:id` — ClawCRM EIR only: respond/resolve feedback

### Org & Tier
- `GET /api/openclaw/org/tier` — Check current plan tier and lead limits
  ```json
  { "orgId": "org_xxx", "tier": "free", "limits": { "leads": 100 }, "upgrade_url": "https://clawcrm.ai/pricing" }
  ```
  Call this if you hit a lead limit error to see current tier and upgrade instructions.

### Health (Call at Every Session Start — Required)
- `GET /api/openclaw/health` — Connectivity check + unread fix notifications
  ```json
  {
    "status": "ok",
    "action_required": true,
    "unread_responses": [
      {
        "feedbackId": "fb_xxx",
        "title": "Enrichment failing for leads",
        "status": "resolved",
        "response": "Enrichment now synchronous. Re-enrich with force:true.",
        "acknowledge": "PATCH /api/openclaw/feedback/fb_xxx { acknowledged: true }"
      }
    ],
    "next_steps": ["Read unread_responses and act on them", "PATCH acknowledged:true when done"]
  }
  ```
  - If `action_required: true` → read `unread_responses`, follow instructions, then PATCH `{ acknowledged: true }`
  - If `action_required: false` → proceed normally

---

## Key Patterns

### Enrichment workflow (correct)
```
// 1. Create
const lead = await POST /api/openclaw/leads { firstName, email, ... }
// 2. Enrich explicitly (NEVER assume auto-enrich worked)
const enriched = await POST /api/openclaw/enrich { leadId: lead.id }
// 3. Verify
if (enriched.status !== "complete") { /* retry or report feedback */ }
```

### Field aliases (both accepted)
- `organizationName` = `clinicName`
- `businessType` = `practiceType`

### crmData vs top-level fields
- **Top-level** (shown in UI enrichment panel): `title`, `seniority`, `companyName`, `linkedinUrl`, `companySize`, `companyRevenue`
- **crmData** (flexible, any custom data): `specialty`, `location`, `clinic_type`, `website`

---

## Pricing
- **Free:** 100 leads, 3 campaigns
- **Pro ($49/mo):** 1,000 leads, unlimited campaigns
- **Ultra ($199/mo):** 5,000 leads, unlimited everything
- Human upgrades at https://clawcrm.ai/pricing

## Docs
OpenAPI spec: https://clawcrm.ai/openapi.json
Human docs: https://clawcrm.ai/api-docs