Skip to main content

LeadVibe API Reference

The LeadVibe API lets you programmatically access lead data, send events, manage scoring rules, and integrate with your existing tools.

Why Use the API?​

The LeadVibe UI is great for daily operations, but the API unlocks deeper integrations:

Send Events from Your App Track user behavior directly from your web app, mobile app, or server—no manual imports needed.

Build Custom Dashboards Pull lead scores and activity data into your own reporting tools, BI platforms, or internal dashboards.

Automate Workflows Create, update, and delete scoring rules programmatically. Build tools that manage LeadVibe configuration at scale.

Sync with Your CRM Push lead scores to Salesforce, HubSpot, or custom CRMs in real-time. Keep your sales team in sync automatically.

Power AI Assistants Beyond our MCP Server, use the API to build custom AI tools that query lead data and answer natural language questions.

Quick Start: Send Your First Event​

Track a page view in under 2 minutes:

Step 1: Get API Credentials

  1. Go to Settings → Integrations → API Secrets
  2. Click Create Secret
  3. Copy your client_id and client_secret

API Secrets page showing the Create Credential form with ingest URL, credential name input, and a table of existing credentials with name, client ID, and creation date

Step 2: Set Your Active OU (one-time setup)

curl -X POST https://your-instance.com/org-units/active \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"ouId": "unit_default"}'

Step 3: Send an Event

curl -X POST https://your-instance.com/ingest \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "alias_kind": "email",
    "alias": "user@example.com",
    "event_type": "page_view"
  }'

Response: 202 Accepted - Your event is queued for processing.

Check the Events page in LeadVibe to see it appear within seconds.

Authentication​

All API requests require HTTP Basic Auth using credentials from Settings → Integrations → API Secrets.

Format: username:password where:

  • username = your client_id
  • password = your client_secret

Example:

curl -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Accept: application/json" \
  "https://your-instance.com/leads"

Security Notes:

  • Treat credentials like passwords—never commit them to version control
  • Rotate secrets regularly via the UI
  • Use environment variables in production

API Design Principles​

RESTful & Predictable Standard HTTP methods (GET, POST, PUT, DELETE) with clear resource paths.

OU-Scoped by Default All data is scoped to your active Organizational Unit. Set it once via /org-units/active, then all subsequent requests use that context automatically.

Async Processing Bulk operations (/ingest, /import) return 202 Accepted immediately and process in the background for speed.

Paginated Results List endpoints support page and limit parameters. Responses include total, page, and limit metadata.

JSON Everywhere All requests and responses use application/json. No XML, no form-encoded data.

Common Workflows​

Workflow 1: Real-Time Event Tracking​

Send events as they happen in your app:

# User opens email
curl -X POST https://your-instance.com/ingest \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "alias_kind": "email",
    "alias": "jane@example.com",
    "event_type": "email_open",
    "timestamp": "2025-01-15T10:30:00Z"
  }'

# User visits pricing page
curl -X POST https://your-instance.com/ingest \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "alias_kind": "email",
    "alias": "jane@example.com",
    "event_type": "page_view",
    "metadata": {
      "page": "/pricing",
      "utm_source": "google"
    }
  }'

Workflow 2: Export Hot Leads for Outreach​

Pull top-scoring leads for your sales team:

# Get top 10 leads with score > 50
curl -u "CLIENT_ID:CLIENT_SECRET" \
  "https://your-instance.com/leads?min_score=50&limit=10"

Response includes:

  • Lead IDs and scores
  • Last activity timestamp
  • Ruleset breakdown
  • Owner assignments

Workflow 3: Programmatic Rule Management​

Create scoring rules via API instead of clicking through the UI:

# Create a ruleset
curl -X POST https://your-instance.com/rulesets \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2025 Campaign",
    "score_type": "engagement",
    "active": true
  }'

# Add rules to the ruleset
curl -X POST https://your-instance.com/rules \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "ruleset_id": "abc-123",
    "event_type": "demo_request",
    "weight": 50
  }'

Workflow 4: Sync Scores to External CRM​

Push lead scores to your CRM hourly:

# Get all leads updated in last hour
curl -u "CLIENT_ID:CLIENT_SECRET" \
  "https://your-instance.com/leads?range=last_1h"

# For each lead, update CRM via their API
# (Your CRM sync logic here)

Endpoint Categories​

Event Ingestion​

Track lead behavior:

  • POST /ingest - Send events in real-time or small batches
  • POST /import - Import historical events in bulk
  • GET /events - Query event history
  • GET /events/{leadID} - Get events for a specific lead
  • GET /events/export - Export events as CSV

Full documentation →

Lead Management​

Access and update lead data:

  • GET /leads - List all leads with scores
  • GET /score/{leadID} - Get a lead's current score
  • GET /lead/{leadID}/score-explain - See how a lead earned their score
  • PATCH /lead/{leadID}/metadata - Update lead profile data
  • DELETE /lead/{leadID} - Remove a lead
  • GET /lead/{leadID}/aliases - List all identifiers for a lead

Full documentation →

Scoring Configuration​

Manage rules programmatically:

  • GET /rulesets - List all rulesets
  • POST /rulesets - Create new ruleset
  • GET /rulesets/{id}/rules - List rules in a ruleset
  • POST /rules - Create scoring rule
  • PUT /rules/{id} - Update rule
  • DELETE /rules/{id} - Delete rule

Full documentation →

Triggers & Automation​

Set up alerts and actions:

  • GET /triggers - List milestone triggers
  • POST /triggers - Create new trigger
  • GET /sequences - List sequence triggers
  • POST /sequences - Create sequence trigger
  • GET /milestone-events - View fired milestone events
  • GET /sequence-events - View fired sequence events

Full documentation →

Analytics & Reporting​

Export data for analysis:

  • GET /top-leads - Highest-scoring leads
  • GET /score-gains - Recent score changes
  • GET /event-stats - Event volume statistics
  • GET /events-analytics - Advanced analytics data
  • GET /usage - Organization usage metrics

Profile & Account Scoring​

Manage fit-based scoring:

  • GET /profile-mappings - Map event metadata to profile fields
  • POST /profile-mappings - Create profile mapping
  • GET /profile-scoring/rulesets - List profile scoring rulesets
  • POST /profile-scoring/rulesets/{id}/rules - Add profile scoring rule

Account Endpoints (Phase 2 - ABM):

note

Account-based marketing (ABM) features are Phase 2 and require abm_enabled: true in organization settings. Contact your account manager for early access.

  • GET /accounts - List account summaries
  • Account-level scoring and intelligence

Configuration & Admin​

Manage settings and team:

  • GET /secrets - List API credentials
  • POST /secrets - Create new credential
  • DELETE /secrets/{id} - Revoke credential
  • GET /members - List team members
  • POST /members - Invite team member
  • GET /event-types - List all tracked event types

Complete Endpoint List​

Event Ingestion:

  • POST /ingest – Ingest events in bulk
  • POST /import – Import historical events
  • GET /stream – Stream real-time updates (SSE)
  • GET /events – List events (with filters)
  • GET /events/{leadID} – List events for a lead
  • GET /events/export – Export events as CSV
  • GET /event-types – List event types
  • GET /event-stats – Event statistics

Lead Management:

  • GET /leads – List lead scores (supports page, limit, min_score, max_score, event_type, last_active, range)
  • GET /score/{leadID} – Fetch lead score
  • GET /lead/{leadID}/score-explain – Score breakdown with top drivers
  • PATCH /lead/{leadID}/metadata – Update lead metadata
  • DELETE /lead/{leadID} – Delete lead
  • GET /lead/{leadID}/deletion – Check deletion status
  • GET /lead/{leadID}/aliases – List lead aliases
  • GET /lead-metadata-properties – List distinct metadata keys

Scoring Rules:

  • GET /rulesets – List rulesets
  • POST /rulesets – Create ruleset
  • GET /rulesets/{id}/rules – List rules for ruleset
  • GET /rules – List all rules
  • POST /rules – Create rule
  • PUT /rules/{id} – Update rule
  • DELETE /rules/{id} – Delete rule

Profile Scoring:

  • GET /profile-mappings – List profile field mappings
  • POST /profile-mappings – Create profile mapping
  • PUT /profile-mappings/{id} – Update mapping
  • DELETE /profile-mappings/{id} – Delete mapping
  • GET /profile-scoring/rulesets – List profile rulesets
  • POST /profile-scoring/rulesets – Create profile ruleset
  • PUT /profile-scoring/rulesets/{id} – Update profile ruleset
  • DELETE /profile-scoring/rulesets/{id} – Delete profile ruleset
  • GET /profile-scoring/rulesets/{id}/rules – List profile rules
  • POST /profile-scoring/rulesets/{id}/rules – Create profile rule
  • PUT /profile-scoring/rulesets/{id}/rules/{ruleId} – Update profile rule
  • DELETE /profile-scoring/rulesets/{id}/rules/{ruleId} – Delete profile rule

Levels:

  • GET /engagement-levels – List engagement levels
  • POST /engagement-levels – Create engagement level
  • PUT /engagement-levels/{id} – Update level
  • DELETE /engagement-levels/{id} – Delete level
  • GET /profile-levels – List profile levels
  • POST /profile-levels – Create profile level
  • PUT /profile-levels/{id} – Update level
  • DELETE /profile-levels/{id} – Delete level

Decay & Filters:

  • GET /decays – List decay rules
  • POST /decays – Create decay rule
  • PUT /decays/{id} – Update decay rule
  • DELETE /decays/{id} – Delete decay rule
  • GET /filters – List inorganic activity filters
  • POST /filters – Create filter
  • PUT /filters/{id} – Update filter
  • DELETE /filters/{id} – Delete filter

Triggers:

  • GET /triggers – List milestone triggers
  • POST /triggers – Create trigger
  • PUT /triggers/{id} – Update trigger
  • DELETE /triggers/{id} – Delete trigger
  • GET /milestone-events – List milestone events
  • GET /milestone-events/export – Export milestone events

Sequences:

  • GET /sequences – List sequence triggers
  • POST /sequences – Create sequence
  • PUT /sequences/{id} – Update sequence
  • DELETE /sequences/{id} – Delete sequence
  • GET /sequence-events – List sequence events
  • GET /sequence-events/export – Export sequence events

Analytics:

  • GET /top-leads – Top leads by score
  • GET /score-gains – Recent score gains
  • GET /events-analytics – Analytics data

Team & Settings:

  • GET /members – List members
  • POST /members – Create member
  • PUT /members/{id} – Update member
  • DELETE /members/{id} – Delete member
  • GET /secrets – List API credentials
  • POST /secrets – Create credentials
  • DELETE /secrets/{id} – Delete credentials
  • GET /usage – Organization usage metrics

Account Endpoints (Phase 2 - ABM):

  • GET /accounts – List account summaries (supports page, limit, search, intent_level, range)

Backfill & Admin:

  • POST /backfill/profile-mappings – Apply profile field mappings to all existing leads
  • POST /backfill/rulesets – Recalculate profile scores for all leads
  • POST /backfill/account-mappings – Apply account field mappings to all accounts
  • POST /backfill/events/account-id – Populate account IDs on event metadata
  • POST /backfill/account-levels – Compute and apply account levels
  • POST /backfill/lead/{leadID}/scores – Recalculate scores for a specific lead

OpenAPI Specification​

For complete, machine-readable API documentation:

View OpenAPI Spec →

Use this with tools like:

  • Postman (import collection)
  • Swagger UI (interactive docs)
  • OpenAPI Generator (generate client SDKs)

Rate Limits​

Standard Limits:

  • 100 requests per minute per API key
  • Burst allowance: 200 requests

Response Headers: Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705329600

429 Too Many Requests: If you exceed limits, you'll get a 429 response. Wait until the reset time or slow down your request rate.

Need Higher Limits? Contact support to discuss increased limits for high-volume integrations.

Best Practices​

1. Use Batch Ingestion Send events in batches of 100-1000 via /ingest instead of individual requests. Much faster and more efficient.

2. Set Active OU Once Call /org-units/active at the start of your session, then all subsequent requests use that context automatically.

3. Handle Async Responses /ingest and /import return 202 Accepted immediately. Don't wait for processing—assume success unless you get an error.

4. Paginate Large Queries Use limit=100 (max) and increment page to avoid timeouts on large datasets.

5. Store Credentials Securely Use environment variables, secret managers, or encrypted config files. Never commit credentials to git.

6. Implement Retry Logic For 5xx errors and rate limits, implement exponential backoff (wait 1s, 2s, 4s, etc. between retries).

7. Use Event Metadata Wisely Attach context to events via the metadata field (e.g., {"page": "/pricing", "utm_source": "google"}). This powers profile scoring and segmentation.

Need Help?​

Found a Bug? Report issues via Help → Report Issue in the app.

Integration Questions? Check our Integrations Guide for HubSpot, Slack, Teams, and MCP Server setup.

Custom Integration Support? Contact your account manager for assistance with complex API integrations.

OpenAPI Spec Issues? The spec is generated from our codebase. If you find discrepancies, let us know via support.