kenbun API Reference

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

Why Use the API?

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

• Send Events from Your App — Track behavior directly from your web app, mobile app, or server
• Build Custom Dashboards — Pull lead scores and activity data into BI platforms or internal dashboards
• Automate Workflows — Create, update, and delete scoring rules programmatically
• Sync with Your CRM — Push lead scores to Salesforce, HubSpot, or custom CRMs in real-time
• Power AI Assistants — Beyond the MCP Server, build custom AI tools that query lead data

Quick Start: Send Your First Event

Track a page view in under 2 minutes.

Step 1: Get API Credentials

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

Alternatively, use a Personal Access Token from Settings → Integrations → Personal Tokens if you want to authenticate as your own user account.

Step 2: Set Your Active Organizational Unit (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 kenbun to see it appear within seconds.

Authentication

kenbun supports three authentication methods.

Personal Access Token (Recommended for personal scripts and MCP)

Generate a PAT from Settings → Integrations → Personal Tokens. Tokens authenticate as your user account with your permissions. Token values start with kbn_pat_.

curl -H "Authorization: Bearer kbn_pat_your_token_here" \
  -H "Accept: application/json" \
  "https://your-instance.com/leads"

Service Account (HTTP Basic Auth)

Use credentials from Settings → Integrations → Service Accounts for shared pipelines and production integrations. These are org-scoped and not tied to any individual user.

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

When to Use Which

Scenario	Recommended Method
MCP Server connection	Personal Access Token
Personal scripts or developer testing	Personal Access Token
Shared production pipeline	Service Account
Event ingestion from your backend	Service Account
CRM sync automation	Service Account

Security Notes:

• Treat all credentials like passwords — never commit them to version control
• Use environment variables in production
• Revoke credentials you no longer use
• Personal Access Tokens can be set to expire automatically

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
• 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

Common Workflows

Real-Time Event Tracking

Send events as they happen in your app:

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"
  }'

Export Hot Leads for Outreach

curl -u "CLIENT_ID:CLIENT_SECRET" \
  "https://your-instance.com/leads?min_score=50&limit=10"

Response includes lead IDs and scores, last activity, ruleset breakdown, and owner assignments.

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 a rule
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}'

Endpoint Categories

Each category links to detailed per-endpoint reference docs.

Event Ingestion

Track lead behavior, query history, export.

• POST /ingest — Send events in real-time or small batches → details
• POST /import — Import historical events in bulk → details
• GET /events — Query event history → details
• GET /events/{leadID} — Events for a lead → details
• GET /events/export — Export events as CSV → details
• GET /event-types — List event types → details
• GET /event-stats — Event statistics → details
• GET /events-analytics — Analytics data → details

Lead Management

Access and update lead data.

• GET /leads — List leads with scores → details
• GET /leads/search — Search by query → details
• GET /score/{leadID} — Current score
• GET /lead/{leadID}/score-explain — Score breakdown → details
• POST /leads/{id}/share-explain — Shareable score link → details
• POST /leads/{leadID}/reset-scores — Reset engagement scores → details
• PATCH /lead/{leadID}/metadata — Update lead metadata → details
• DELETE /lead/{leadID} — Remove a lead → details
• GET /lead/{leadID}/aliases — List lead aliases → details
• GET /lead-by-alias — Lookup by alias → details
• POST /leads/import/preview, /start, /jobs — Bulk CSV import → details
• POST /leads/merge — Merge two leads → details

Scoring Rules & Levels

Engagement and profile scoring configuration.

• GET /engagement-scoring/rulesets — Engagement rulesets → details
• GET /engagement-scoring/rules — Engagement rules → details
• GET /profile-scoring/mappings — Profile mappings → details
• GET /profile-scoring/rulesets — Profile rulesets → details
• GET /engagement-scoring/levels, /profile-scoring/levels — Score thresholds → Engagement Levels, Profile Levels
• GET /decays — Decay rules → details
• GET /filters — Inorganic activity filters → details

Test rule changes against existing data:

• POST /engagement-scoring/test, /profile-scoring/test, /account-scoring/test, /deal-scoring/test
• POST /scoring/rulesets/{dimension}/{id}/score-now — On-demand rescoring

Triggers & Automation

• GET /triggers, POST /triggers — Milestone triggers
• GET /sequences, POST /sequences — Sequence triggers
• GET /surge-triggers, POST /surge-triggers — Surge triggers
• POST /triggers/{id}/simulate, /sequences/{id}/simulate, /surge-triggers/{id}/simulate — Test against a lead
• POST /surge-triggers/{id}/preview — Aggregate backtest across all leads
• GET /milestone-events, /sequence-events — View fired events

See full reference under the API Routes → Triggers section in the sidebar.

Account & Buying Committee

• GET /accounts — List accounts → details
• GET /accounts/{id} — Account detail → details
• POST /accounts/{id}/merge — Merge accounts → details
• GET /buying-committee — Buying committee members → details

Analytics & Reporting

• GET /top-leads — Highest-scoring leads
• GET /score-gains — Recent score changes
• GET /deals/attribution-insights — Patterns across closed-won deals → details
• GET /usage — Organization usage metrics

Configuration & Admin

• GET /secrets, POST /secrets — Service account credentials
• POST /settings/tokens — Personal Access Tokens
• GET /members, POST /members — Team management → details
• POST /backfill/* — Apply changes retroactively to existing data

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:

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.

Best Practices

1. Use Batch Ingestion — Send events in batches of 100-1000 via /ingest instead of individual requests
2. Set Active OU Once — Call /org-units/active at the start of your session
3. Handle Async Responses — /ingest and /import return 202 Accepted immediately
4. Paginate Large Queries — Use limit=100 (max) and increment page to avoid timeouts
5. Store Credentials Securely — Use environment variables or secret managers
6. Implement Retry Logic — For 5xx errors and rate limits, use exponential backoff
7. Use Event Metadata Wisely — Attach context via the metadata field; this powers profile scoring and segmentation

Need Help?

• Found a Bug? Report via Help → Report Issue in the app
• Integration Questions? See the Integrations Guide
• Custom Integration Support? Reach out to support@kenbun.io