API & Integrations

MCP (Model Context Protocol) lets AI assistants use Kolvera as a tool. You talk in plain English, the AI calls Kolvera behind the scenes.

Setup Guide (5 steps)

Step 1: Generate your config

Go to Integrations and click Generate Config on the AI Assistant (MCP) card.

Step 2: Copy the config

Click Copy to copy the JSON config to your clipboard.

Step 3: Open Claude Desktop settings

In Claude Desktop, go to Settings → Developer → Edit Config.

Step 4: Find the config file

Edit Config opens your file explorer. Open claude_desktop_config.json in any text editor.

Step 5: Paste and save

If the file is empty or only has {}, paste the entire config you copied.
If it already has content (like a "preferences" section), paste the "kolvera": { ... } block inside the existing "mcpServers" object. If there’s no "mcpServers" key, add one at the top level.
Save the file and restart Claude Desktop. You should see "kolvera" with a green running badge in Settings → Developer.

Requires Node.js — the config uses npx mcp-remote to connect. If you don’t have Node.js, install it here (LTS version recommended).

98 Tools Available

You don’t need to memorise these — just describe what you want and the AI picks the right tool.

Contacts (11 tools)

Credits (3 tools)

Companies (7 tools)

Campaigns (18 tools)

Pipeline (2 tools)

Deep Research (4 tools)

Hot Lists (7 tools)

Ideal Client Profiles (12 tools)

MPC Profiles (6 tools)

Business Contexts (5 tools)

Job Scraping (10 tools)

Ideal Candidates (6 tools)

Meetings & Fathom (7 tools)

Example Conversations

Base URL: https://www.kolvera.io/api/v2
Auth: Authorization: Bearer kv_your_token (or OAuth access token)

Contacts (7)

Companies (6)

Campaigns (7)

Hot Lists (5)

ICP Profiles (5)

Meetings (4)

Pipeline & Research (5)

Credits & Webhooks (5)

Quick Test

curl -H "Authorization: Bearer kv_your_token" \
  "https://www.kolvera.io/api/v2/credits"

# Response:
# {"ok": true, "plan_balance": 847, "addon_balance": 150, "total": 997}

Instead of polling the API to check “did anyone reply?”, Kolvera sends a POST request to your URL the moment it happens. Connect to Slack, Zapier, Make, or your own server.

Setup in 3 Steps

1. Pick a URL that can receive POST requests (Slack hook, Zapier trigger, your server, etc.)
2. Register:

   curl -X POST https://www.kolvera.io/api/v2/webhooks \
     -H "Authorization: Bearer kv_your_token" \
     -H "Content-Type: application/json" \
     -d '{"url": "https://hooks.zapier.com/your-hook",
          "events": ["campaign.replied", "contact.enriched"],
          "secret": "optional_signing_key"}'

3. Kolvera sends a JSON POST to your URL when the event fires

All 14 Events

Verifying Signatures

If you set a secret, every webhook includes an X-Kolvera-Signature header (HMAC-SHA256 of the body). Verify it to confirm the request came from Kolvera:

import hmac, hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Subscriptions auto-disable after 10 consecutive delivery failures.

Outputs JSON. Pipe to jq for formatting, save to files, or chain in shell scripts.

Setup

# Linux / Mac
export KOLVERA_API_KEY=kv_your_token

# Windows PowerShell
$env:KOLVERA_API_KEY = "kv_your_token"

Contacts

# Search contacts with filters
python kolvera_cli.py contacts search "developer" --has-email yes --sort updated_at

# Get full contact detail
python kolvera_cli.py contacts get <contact_id>

# Create a contact (auto-links company)
python kolvera_cli.py contacts create --first-name "Sarah" --last-name "Chen" \
  --email "sarah@acme.com" --company "Acme Corp" --prospect

# Find email for a contact (2cr if found)
python kolvera_cli.py contacts find-email <contact_id>

# Find phone (2-6cr if found)
python kolvera_cli.py contacts find-phone <contact_id>

Companies

# Search by industry and state
python kolvera_cli.py companies search "recruitment" --state VIC --industry "Staffing"

# View company detail
python kolvera_cli.py companies get <company_id>

# List contacts at a company
python kolvera_cli.py companies contacts <company_id>

Campaigns

# List campaigns (optionally filter by status)
python kolvera_cli.py campaigns list --status active

# View campaign detail with steps
python kolvera_cli.py campaigns get <campaign_id>

# Check performance stats
python kolvera_cli.py campaigns stats <campaign_id>

# Pause / resume
python kolvera_cli.py campaigns pause <campaign_id>
python kolvera_cli.py campaigns resume <campaign_id>

# Enrol contacts into a campaign
python kolvera_cli.py campaigns enrol <campaign_id> --contact-ids id1 id2 id3

Pipeline, Research & Credits

# Search pipeline jobs
python kolvera_cli.py pipeline search "python" --state-filter NSW

# View job detail
python kolvera_cli.py pipeline get <job_id>

# Trigger Deep Research (3cr)
python kolvera_cli.py research trigger "AU fintech companies in Melbourne"

# View research results
python kolvera_cli.py research get <report_id>

# List all research reports
python kolvera_cli.py research list

# Check credit balance
python kolvera_cli.py credits

Practical: Batch Enrich and Enrol

# Find contacts without emails, enrich them, enrol verified ones
CONTACTS=$(python kolvera_cli.py contacts search --has-email no --per-page 100)

# Get IDs
echo "$CONTACTS" | jq -r '.contacts[].id' | while read ID; do
  python kolvera_cli.py contacts find-email "$ID"
  sleep 2
done

# Check balance after enrichment
python kolvera_cli.py credits

Building an app that connects to Kolvera on behalf of other users? Use OAuth instead of API tokens. Each user gets their own authorised connection with specific permissions.

How It Works

1. Your app redirects the user to Kolvera’s consent screen
2. They see what permissions your app is requesting and click “Authorise”
3. Kolvera redirects back with a temporary code
4. Exchange the code for an access token (1hr) and refresh token (30 days)
5. Use the access token on /api/v2/* endpoints like any Bearer token

Endpoints

17 Permission Scopes

PKCE (S256) supported for public clients. Access tokens expire after 1 hour.